MCP¶

Model Context Protocol server：把网关的工具暴露给 LLM 客户端。两种 transport：stdio / HTTP。

完整 60 tool 参数级文档

本页是工具清单概览. 每个 tool 的完整参数 (含 v1.4.83/84 alias + enum 双接 + deny_unknown_fields + runtime validate) / JSON-RPC 调用示例见 API 参考 → MCP 工具 (v1.4.85 新增).

工具清单¶

行情（qot:read）¶

工具	说明
`futu_ping`	ping 网关，返回 RTT
`futu_get_quote`	实时报价（自动订阅 Basic）
`futu_get_snapshot`	快照（含 52 周高低、换手率、买卖档）
`futu_get_kline`	历史 K 线（日 / 周 / 月 / 1-60 分钟）
`futu_get_orderbook`	买卖盘（自动订阅 OrderBook）
`futu_get_ticker`	逐笔成交
`futu_get_rt`	分时图
`futu_get_static`	静态信息（名称、每手股数、上市日）
`futu_get_broker`	经纪商队列（港股）
`futu_list_plates`	板块列表
`futu_plate_stocks`	板块成分股
`futu_get_capital_flow`	v1.4.25+：资金流时间序列（主力资金进出）
`futu_get_capital_distribution`	v1.4.25+：资金分布（超大 / 大 / 中 / 小单）
`futu_get_market_state`	v1.4.25+：市场状态（开盘 / 休市 / 午休）
`futu_get_history_kline`	v1.4.26+：历史 K 线（支持 rehab_type + 大数据量 max_count）
`futu_get_owner_plate`	v1.4.26+：股票所属板块（行业 / 概念 / 地域）
`futu_get_reference`	v1.4.26+：关联证券（正股↔涡轮/期货/期权）
`futu_get_option_chain`	v1.4.26+：期权链（按到期日聚合 call/put）
`futu_get_warrant`	v1.4.29+：涡轮列表（按成交量排序，可指定正股）
`futu_get_ipo_list`	v1.4.29+：新股 IPO 列表（港/美/A 股按市场）
`futu_get_future_info`	v1.4.29+：期货合约资料（合约大小、最后交易日、交易时段）
`futu_get_user_security_group`	v1.4.29+：自选股分组列表（自定义 / 系统）
`futu_get_stock_filter`	v1.4.29+：条件选股（最小参数；高级 filter 走 REST）
`futu_get_trading_days`	v1.4.30+：交易日列表
`futu_get_rehab`	v1.4.30+：复权因子（长期 K 线对齐 / 回测必用）
`futu_get_suspend`	v1.4.30+：停牌日
`futu_get_user_security`	v1.4.30+：自选股分组下的股票
`futu_get_global_state`	v1.4.30+：网关全局状态（市场开闭 / 登录状态 / 服务器版本）
`futu_get_user_info`	v1.4.30+：用户信息（各市场行情权限 / 订阅配额）
`futu_get_delay_statistics`	v1.4.30+：延迟统计概要
`futu_get_history_kl_quota`	v1.4.30+：历史 K 线下载配额
`futu_get_used_quota`	v1.4.110+：当前已用订阅额度和历史 K 线额度
`futu_get_holding_change`	v1.4.30+：持股变动（高管 / 机构 / 基金）
`futu_modify_user_security`	v1.4.30+：修改自选股分组（add / del / move-out）
`futu_get_code_change`	v1.4.30+：代码变更 / 临时代码（目前港股）
`futu_set_price_reminder`	v1.4.30+：设置到价提醒
`futu_get_price_reminder`	v1.4.30+：查询到价提醒
`futu_get_option_expiration_date`	v1.4.30+：期权到期日列表
`futu_query_subscription`	v1.4.30+：查询当前订阅状态
`futu_unsubscribe`	v1.4.30+：反订阅行情（支持 unsub_all）

账户只读（acc:read）¶

工具	说明
`futu_list_accounts`	交易账户列表
`futu_get_funds`	资金概览
`futu_get_positions`	持仓
`futu_get_orders`	当日订单
`futu_get_deals`	当日成交
`futu_get_max_trd_qtys`	v1.4.25+：下单前算最大可买卖量
`futu_get_order_fee`	v1.4.25+：手续费明细
`futu_get_margin_ratio`	v1.4.25+：融资融券比率
`futu_get_history_orders`	v1.4.25+：历史订单
`futu_get_history_deals`	v1.4.25+：历史成交
`futu_sub_acc_push`	v1.4.30+：订阅账户推送（订单 / 成交更新）
`futu_get_acc_cash_flow`	v1.4.30+：账户资金流水（按清算日）

交易（trade:real / trade:simulate）¶

工具	说明	额外参数
`futu_place_order`	下单	`api_key?` per-call 覆盖
`futu_modify_order`	改单（含撤单）	`api_key?`
`futu_cancel_order`	撤单（简化版）	`api_key?`
`futu_reconfirm_order`	二次确认订单	`api_key?`
`futu_cancel_all_order`	v1.4.30+：全部撤单（指定市场或全账户）	`api_key?`

解锁交易（trade:unlock，v1.4+）¶

工具	说明	额外参数
`futu_unlock_trade`	解锁 / 锁回真实交易	`unlock: bool`（默认 true）；v1.4.31+ `otp: String` 可选（2FA 账户）；v1.4.47+ `security_firm: i32` 可选（1-7 / FutuHK / hk），只解该券商；v1.4.47+ `acc_ids: Vec<u64>` 可选，只解列表内账户（和 security_firm 取交集，解决影子子账户）

明文密码永不入 LLM prompt：服务端从 OS keychain 读（优先）或 FUTU_TRADE_PWD 环境变量（次选）
运维用 futucli set-trade-pwd 把密码写进 keychain；LLM 只调 futu_unlock_trade 工具，密码流转完全不经过模型
MD5 在服务端本地计算后再发给 gateway
解锁后 gateway 进程级缓存 cipher，直到 gateway 重启；下单不需要每次重解锁
v1.4.31+ per-broker 解锁 + 细粒度返回：响应 JSON 带 total_requested / total_unlocked / failed_accounts，出部分失败时 ok=false 会明确指出哪个账户没解锁（常见原因：该账户品种权限未开通 / 影子子账户）
v1.4.31+ 2FA（令牌动态密码）账户：服务端返 need_otp=true 时 LLM 应提示用户输入 OTP，再调一次带 otp 字段

启动¶

stdioHTTP（v1.0+）

export FUTU_MCP_API_KEY="fc_xxxx..."
./futu-mcp \
  --gateway 127.0.0.1:11111 \
  --keys-file ~/.config/futu/keys.json

stdin / stdout 传 JSON-RPC 帧，由 LLM 客户端启动子进程。

./futu-mcp \
  --gateway 127.0.0.1:11111 \
  --keys-file ~/.config/futu/keys.json \
  --http-listen 127.0.0.1:38765

POST /mcp —— rmcp streamable HTTP transport
GET /metrics —— Prometheus（无需 token）
GET /.well-known/oauth-protected-resource —— OAuth2 Protected Resource Metadata（RFC 9728，v1.4+；让 MCP 客户端自动发现 scope 要求）

OAuth metadata 端点（v1.4+）¶

未带 Authorization: Bearer 头的 /mcp 请求会返回 401 + WWW-Authenticate: Bearer resource_metadata="/.well-known/oauth-protected-resource" 头。客户端按这个 URL 拉 JSON 即可知道要带什么 scope：

{
  "resource": "/mcp",
  "bearer_methods_supported": ["header"],
  "scopes_supported": [
    "qot:read",
    "acc:read",
    "trade:simulate",
    "trade:real",
    "trade:unlock"
  ],
  "resource_name": "FutuOpenD-rs MCP",
  "resource_documentation": "https://futuapi.com/guide/mcp/"
}

为什么不是完整 OAuth server？

Futu 的 API key 是人工配置的长期凭据，没有 interactive consent 流程。 RFC 9728 正是为"只声明鉴权要求、不做授权流程"的资源服务器设计。实际 token（= API key）仍由运维线下发放，写进 MCP client 配置里的 Authorization 头。

per-call API key 优先级（v1.1+）¶

1. tool args 里显式的 `api_key` 字段
2. HTTP Authorization: Bearer <token>（仅 HTTP transport）
3. 启动时 --api-key / FUTU_MCP_API_KEY 环境变量

stdio 模式下没 HTTP header → 自动回落 2→3。HTTP 模式下多 LLM 各带自己 token，audit / 限额各记各的。

scope 中央注册表¶

guard::scope_for_tool(name) -> Option<ToolScope> 是唯一真源。加新 #[tool] 必须同步更新这里，否则 handler 返回 unknown MCP tool；测试 all_known_tools_have_scopes 会挂。

SIGHUP 热重载¶

kill -HUP $(pgrep futu-mcp)

改了 keys.json 里某把 key 的 scope / 限额 / expires_at / 吊销后立刻对 MCP 生效（v0.8+ 起 MCP 按 key_id 每次请求现查 KeyStore）。

交易工具的安全边界¶

unlock_trade 工具不接受密码参数（v1.4+）—— futu_unlock_trade 只有 unlock: bool 入参；密码由服务端从 OS keychain / 环境变量读。LLM prompt 和工具调用日志里永远看不到密码
simulate 默认 —— PlaceOrderReq.env 默认值是 "simulate"，LLM 要显式写 "real" 才走真实账户
scope 隔离 —— trade:simulate 永远不能下真实单（即使把 env 写成 real 也会被 require_trading 拒）
限额必过 —— handler 层走 full CheckCtx：market / symbol / value / side / daily 全套检查
WS 推送防御深度（v1.4+）—— 就算订阅门禁漏了，push 分发前也会按 scope 再过一遍，过滤掉的推送打 futu_ws_push_filtered_total 指标

MCP 客户端对接¶

完整教程 → MCP 接入 LLM 包含 Claude Desktop / Cursor / Continue 的配置示例。