AI导哈

交易数据协议服务器

Futu MCP Server 是为富途交易平台提供的模型上下文协议服务器，为AI助手提供实时市场数据、交易操作、账户管理等功能。

  • by johntyty912
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 johntyty912/futu-mcp

使用说明

富图MCP服务器

全面 模型上下文协议（MCP） 服务器 富途交易平台，为人工智能助手提供实时市场数据、交易操作、账户管理等。

特性

🔍 市场数据工具（8个工具）

  • 实时行情 -获取当前股票价格、交易量、买入/卖出价
  • 历史K线数据 -访问烛台数据进行回溯测试
  • 市场快照 -多种证券概述
  • 订单簿 -市场深度与买卖水平
  • 逐笔交易数据 -实时交易流
  • 期权链 -希腊和IV选项数据
  • 市场状态 -交易时间和市场状况
  • 静态信息 -安全基础

💹 交易工具（9种工具）

  • 下订单 -使用多种订单类型（限价、市价、止损等）进行买卖
  • 修改订单 -更新价格、数量或取消订单
  • 取消订单 -单笔或批量订单取消
  • 订单列表 -查看未结订单和历史订单
  • 交易列表 -今天执行的交易
  • 历史交易 -长达90天的交易历史
  • 最大交易量 -计算购买力

💰 账户管理工具（3个工具）

  • 账户信息 -平衡、购买力、资产
  • 职位 -损益表中的当前持股
  • 现金流 -交易历史

📊 观察名单和警报（2个工具）

  • 收看列表 -管理安全组
  • 价格提醒 -设置价格提醒和通知

📅 市场信息（2个工具）

  • 交易日历 -获取交易日
  • 静态信息 -安全详细信息

总计：24个综合工具 涵盖交易和市场分析的各个方面。

先决条件

1.FutuOpenD网关

FutuOpenD需要与Futu服务器通信。下载并安装：

启动FutuOpenD:

# Default: localhost:11111
./FutuOpenD

2.Footu账户

  • 在以下网址创建Futu帐户 页脚
  • 交易：完成KYC并为您的账户充值
  • 对于纸质交易：使用模拟模式（不需要真钱）

3.Python 3.12+

确保安装了Python 3.12或更高版本。

安装

使用紫外线（推荐）

# Clone the repository
git clone <repository-url>
cd futu-mcp

# Install with uv
uv sync

# Or install from PyPI (when published)
uv pip install futu-mcp

使用pip

pip install -e .

配置

环境变量

创建一个 .env 项目根目录中的文件：

# FutuOpenD Connection
FUTU_HOST=127.0.0.1
FUTU_PORT=11111

# Trading Password (required for real trading)
FUTU_TRADE_PWD=your_trading_password

# Timeouts (seconds)
FUTU_CONNECTION_TIMEOUT=30
FUTU_REQUEST_TIMEOUT=60

# Market Data
FUTU_MAX_SUBSCRIPTION_QUOTA=500

安全说明：从不承诺 .env 文件到版本控制！

用法

运行MCP服务器

服务器以stdio模式（标准输入/输出）运行，这是MCP服务器与客户端通信的标准方式。

# Using uv
uv run futu-mcp-server

# Or directly with Python
python -m futu_mcp.server

服务器将启动并通过stdio等待MCP请求。它通常由MCP客户端（Cursor、Claude Desktop等）自动启动。

Docker部署

Docker Compose快速入门

# Build and start the server
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f futu-mcp

# Stop the server
docker-compose down

手动Docker构建和运行

# Build the image
docker build -t futu-mcp:latest .

# Run with host networking (easiest for FutuOpenD access)
docker run -d \
  --name futu-mcp-server \
  --network host \
  -e FUTU_HOST=127.0.0.1 \
  -e FUTU_PORT=11111 \
  futu-mcp:latest

# View logs
docker logs futu-mcp-server

看 部署.md 获取全面的部署指南。

MCP客户端配置

用于游标IDE

添加到您的 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "futu": {
      "command": "uv",
      "args": ["run", "futu-mcp-server"],
      "cwd": "/path/to/futu-mcp",
      "env": {
        "FUTU_HOST": "127.0.0.1",
        "FUTU_PORT": "11111"
      }
    }
  }
}

适用于克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "futu": {
      "command": "uv",
      "args": ["run", "futu-mcp-server"],
      "cwd": "/path/to/futu-mcp",
      "env": {
        "FUTU_HOST": "127.0.0.1",
        "FUTU_PORT": "11111"
      }
    }
  }
}

反重力

加入你的反重力 mcp_config.json:

{
  "mcpServers": {
    "futu": {
      "command": "uv",
      "args": ["run", "futu-mcp-server"],
      "cwd": "/path/to/futu-mcp",
      "env": {
        "FUTU_HOST": "127.0.0.1",
        "FUTU_PORT": "11111"
      }
    }
  }
}

看 mcp配置示例/antigravity-config.json 对于完整的示例配置。

查询示例

连接到MCP客户端后，您可以问：

市场数据

  • “获取腾讯实时报价（HK.00700）”
  • “显示2024年1月1日至2024年12月31日AAPL的历史每日数据”
  • “美国股市目前的市场状况如何？”
  • “获取特斯拉的订单簿”

交易

  • “以150美元的价格限价买入100股苹果股票”
  • “取消订单ID 12345”
  • “显示我所有的未结订单”
  • “我对TSLA的最大购买力是多少？”

账户

  • “显示我的账户余额和购买力”
  • “列出我目前的所有职位”
  • “获取我上个月的现金流历史记录”

分析

  • “获取SPY的期权链”
  • “显示2024年1月美国市场的交易日”
  • “当AAPL超过200美元时设置价格警报”

工具参考

市场数据

get_stock_quote

stock_codes: list[str]  # e.g., ["HK.00700", "US.AAPL"]

get_historical_kline

stock_code: str         # e.g., "HK.00700"
start_date: str        # "2024-01-01"
end_date: str          # "2024-12-31"
kl_type: str          # K_1M, K_5M, K_15M, K_30M, K_60M, K_DAY, K_WEEK, K_MON
autype: str           # qfq (forward), hfq (backward), None
max_count: int        # default 1000

get_market_snapshot

stock_codes: list[str]

get_order_book

stock_code: str

get_rt_ticker

stock_code: str
max_count: int        # default 1000

get_option_chain

stock_code: str       # underlying
start_date: str      # optional, "yyyy-MM-dd"
end_date: str        # optional, "yyyy-MM-dd"

get_market_state

stock_codes: list[str]  # optional

交易

place_order

stock_code: str
trd_side: str         # BUY or SELL
order_type: str       # NORMAL, MARKET, STOP, STOP_LIMIT, etc.
qty: float
price: float         # optional, required for limit orders
trd_env: str         # REAL or SIMULATE (default SIMULATE)
trd_market: str      # HK, US, CN, etc. (optional)
remark: str          # optional, max 64 bytes

modify_order

order_id: str
modify_op: str       # CANCEL, MODIFY, ENABLE, DISABLE
qty: float          # optional, for MODIFY
price: float        # optional, for MODIFY
trd_env: str        # default SIMULATE

cancel_order

order_id: str
trd_env: str        # default SIMULATE

cancel_all_orders

trd_env: str        # default SIMULATE

get_order_list

trd_env: str         # default SIMULATE
trd_market: str      # optional
status_filter: list[str]  # optional

get_deal_list

trd_env: str         # default SIMULATE
trd_market: str      # optional

get_history_deal_list

start_time: str      # "YYYY-MM-DD HH:MM:SS"
end_time: str        # "YYYY-MM-DD HH:MM:SS"
trd_env: str         # default SIMULATE

get_max_trd_qtys

stock_code: str
order_type: str
trd_side: str
price: float         # optional
trd_env: str         # default SIMULATE

账户管理

get_account_info

trd_env: str         # default SIMULATE
trd_market: str      # optional

get_positions

trd_env: str         # default SIMULATE
trd_market: str      # optional

get_cash_flow

start_date: str      # "YYYY-MM-DD"
end_date: str        # "YYYY-MM-DD"
trd_env: str         # default SIMULATE

观察名单和警报

get_watchlist

group_name: str      # optional, default "All"

set_price_reminder

stock_code: str
operation: str       # ADD, DEL, ENABLE, DISABLE, MODIFY, DEL_ALL
reminder_type: str   # optional, PRICE_UP, PRICE_DOWN, etc.
reminder_value: float  # optional, threshold
note: str           # optional, max 64 bytes

市场行情

get_trading_days

market: str          # HK, US, CN, etc.
start_date: str      # "yyyy-MM-dd"
end_date: str        # "yyyy-MM-dd"

get_static_info

stock_codes: list[str]

交易安全

纸面交易（默认）

所有交易操作默认为 模拟 安全模式（纸币交易）。没有真正的钱处于危险之中。

# Paper trading (default)
place_order(..., trd_env="SIMULATE")

真实交易

用真钱交易：

  1. 集 FUTU_TRADE_PWD 在你的 .env 文件
  2. 使用 trd_env="REAL" 在交易操作中
  3. 确保FutuOpenD已连接到您的真实帐户
# Real trading (use with caution!)
place_order(..., trd_env="REAL")

⚠️ 警告真实交易涉及金融风险。执行前务必核实订单。

股票代码格式

Futu使用特定的股票代码格式：

  • 香港: HK.00700 （腾讯）
  • 美国股票: US.AAPL 苹果
  • 中国A股: SH.600000 （上海）， SZ.000001 （深圳）
  • 新加坡: SG.D05 （DBS）
  • 日本: JP.7203 （丰田）

错误处理

服务器实现了全面的错误处理：

  • 连接错误：FutuOpenD未运行或主机/端口错误
  • 身份验证错误：交易密码无效
  • API错误：参数无效，权限不足
  • 速率限制：使用指数回退自动重试

所有错误都会返回清晰、可操作的消息。

日志记录

日志以以下格式输出到stdout：

2024-01-01 12:00:00 - futu_mcp.server - INFO - Order placed: HK.00700 BUY 100 @ 350.0

通过设置调整日志级别 LOG_LEVEL 环境变量：

LOG_LEVEL=DEBUG uv run futu-mcp-server

发展

运行测试

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=futu_mcp

代码质量

# Format code
uv run ruff format .

# Lint
uv run ruff check .

# Type check
uv run mypy src/futu_mcp

项目结构

futu-mcp/
├── src/
│   └── futu_mcp/
│       ├── __init__.py
│       ├── server.py          # Main MCP server
│       ├── config.py          # Configuration
│       ├── models.py          # Pydantic models
│       ├── futu_client.py     # Futu API wrapper
│       └── tools/             # Tool implementations
│           ├── __init__.py
│           ├── market_data.py
│           ├── trading.py
│           ├── account.py
│           ├── watchlist.py
│           └── market_info.py
├── tests/
├── pyproject.toml
├── README.md
└── .env.example

故障排除

FutuOpenD连接失败

FutuConnectionError: Failed to connect to FutuOpenD

解决方案:

  • 确保FutuOpenD正在运行
  • 检查 FUTU_HOST 和 FUTU_PORT 设置
  • 验证防火墙设置

解锁交易失败

FutuConnectionError: Failed to unlock trade

解决方案:

  • 验证 FUTU_TRADE_PWD 是正确的
  • 确保您正在使用 trd_env="REAL"
  • 检查您的帐户是否具有交易权限

已超出订阅配额

FutuAPIError: Subscription quota exceeded

解决方案:

  • 取消订阅未使用的证券
  • 通过升级帐户级别增加配额
  • 使用 max_subscription_quota 配置

股票代码无效

FutuAPIError: Invalid stock code format

解决方案:

  • 使用正确的格式： HK.00700, US.AAPL, SH.600000
  • 验证证券是否存在并可交易

支持的市场

  • 🇭🇰 香港（HK）-股票、交易所买卖基金、认股权证、期权、期货
  • 🇺🇸 美国（US）-股票、ETF、期权、期货
  • 🇨🇳 中国（CN）-A股、ETF
  • 🇸🇬 新加坡（SG）-股票、ETF、期货
  • 🇯🇵 日本（JP）-股票、ETF、期货

局限性

  • 票据交易：某些功能在模拟模式下可能不可用
  • 速率限制：API调用受Futu的速率限制
  • 市场数据：需要适当的订阅级别
  • 真实交易：需要资金账户和交易密码

资源

贡献

欢迎投稿！请遵循以下指南：

  1. 分叉存储库
  2. 创建要素分支
  3. 为新功能编写测试
  4. 确保所有测试通过
  5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

免责声明

该软件用于教育和研究目的。股票交易涉及风险。作者不对因使用本软件而产生的任何经济损失负责。在用真钱交易之前，一定要核实交易并了解风险。

支持

对于问题和疑问：

  • 在GitHub上打开一个问题
  • 查看Futu API文档
  • 审查MCP协议规范

内置于❤️ 使用模型上下文协议

相关 MCP