futu-stock 技能

基于富途 OpenAPI 的股票行情技能，通过 MCP 协议访问港股、美股、A 股实时行情、K 线、期权及账户信息。

MCP 源码: https://github.com/shuizhengqi1/futu-stock-mcp-server

一、整体流程

┌─────────────────────────────────────────────────────────────────────────┐
│ 1. 环境检测 │
│ ├─ 检测 python3、futu-mcp-server、mcp 包、OpenD 状态 │
│ └─ 输出检测结果 │
├─────────────────────────────────────────────────────────────────────────┤
│ 2. 依赖处理 │
│ ├─ 若缺少 futu-mcp-server → 执行 pipx install futu-stock-mcp-server │
│ ├─ 若缺少 mcp 包 → 执行 pip install mcp │
│ └─ 若 OpenD 已安装但未启动 → 调用时尝试启动（需配置 OPEND_PATH） │
├─────────────────────────────────────────────────────────────────────────┤
│ 3. 查询逻辑 │
│ ├─ 有明确股票代码（如 HK.00700、US.AAPL）→ 直接调用 getstockquote / │
│ │ getmarketsnapshot / gethistorykline 等 │
│ └─ 无股票代码（如「港股 10–50 元的股票」）→ 使用 getstockfilter 筛选 │
└─────────────────────────────────────────────────────────────────────────┘

二、环境检测与依赖处理

2.1 执行环境检测

bash
cd {baseDir}
python3 executor.py --check-env

输出示例：

• - python3: OK / 缺失
• futu-mcp-server: OK / 缺失
• mcp 包: OK / 缺失
• OpenD (FUTUHOST:FUTUPORT): 监听中 / 未监听

2.2 依赖缺失时的安装

2.3 OpenD 安装与启动

下载: https://openapi.futunn.com/futu-api-doc/opend/opend-cmd.html

配置 FutuOpenD.xml：

• - loginaccount: 富途账号
• loginpwd: 登录密码
• api_port: 默认 11111
• ip: 默认 127.0.0.1

启动：
bash

Linux/macOS

Windows

2.4 调用时自动启动 OpenD

若已安装 OpenD 但未启动，可设置 OPEND_PATH 环境变量，executor 在检测到端口未监听时会尝试启动：

bash
export OPEND_PATH=/path/to/opend/directory # 含 FutuOpenD 可执行文件的目录

三、查询逻辑（核心规则）

3.1 有明确股票代码

用户给出具体代码（如 HK.00700、00700、腾讯 且能映射到代码）时，直接按代码查询：

股票代码格式: {市场}.{代码}

• - 港股: HK.00700
• 美股: US.AAPL
• 沪市: SH.600519
• 深市: SZ.000001

3.2 无股票代码（条件筛选）

用户只给条件（如「港股 10–50 元的股票」「纳斯达克涨幅前 20」）时，使用 getstockfilter：

json
{
tool: getstockfilter,
arguments: {
market: HK.Motherboard,
base_filters: [{
field_name: 5,
filter_min: 10.0,
filter_max: 50.0,
sort_dir: 1
}],
page: 1,
page_size: 50
}
}

常用 market 值:

• - HK.Motherboard 港股主板
• HK.GEM 港股创业板
• US.NASDAQ 纳斯达克
• US.NYSE 纽交所
• SH.3000000 沪市主板
• SZ.3000004 深市创业板

basefilters 常用 fieldname（参考富途 StockField）:

• - 5: 当前价
• 6: 涨跌幅
• 7: 成交量
• 8: 成交额
• 1: 排序

四、可用工具

行情

• - getstockquote: 报价
• getmarketsnapshot: 快照（含买卖盘）
• getcurkline: 当前 K 线（需先 subscribe）
• gethistorykline: 历史 K 线
• getrtdata: 实时数据（需 subscribe RTDATA）
• getticker: 逐笔（需 subscribe TICKER）
• getorderbook: 买卖盘（需 subscribe ORDERBOOK）
• getbroker_queue: 经纪队列（需 subscribe BROKER）

订阅

• - subscribe: 订阅 QUOTE / ORDERBOOK / TICKER / RTDATA / BROKER / K1M / KDAY 等
• unsubscribe: 取消订阅

期权

• - getoptionchain: 期权链
• getoptionexpirationdate: 到期日
• getoptioncondor: 鹰式策略
• getoption_butterfly: 蝶式策略

账户

• - getaccountlist: 账户列表
• getfunds: 资金
• getpositions: 持仓
• getmaxpower: 最大交易力
• getmarginratio: 保证金比例

市场

• - getmarketstate: 市场状态
• getsecurityinfo: 证券信息
• getsecuritylist: 证券列表
• getstockfilter: 条件筛选（无代码时使用）

五、调用方式

执行工具

bash
cd {baseDir}
python3 executor.py --call {tool: getmarketsnapshot, arguments: {symbols: [HK.00700]}}

查看工具参数

bash
cd {baseDir}
python3 executor.py --describe getstockfilter

列出所有工具

bash
cd {baseDir}
python3 executor.py --list

六、常见问题

Q1: futu-mcp-server 找不到

bash
pipx install futu-stock-mcp-server

或

Q2: 连接 OpenD 失败 / 端口未监听

bash

检查端口

或

未监听则启动 OpenD（见 2.3）

或配置 OPEND_PATH