ClawHub

Futu-Stock

MCP Tools

Access Futu stock market data via MCP server - real-time quotes, K-lines, options, account info for HK/US/CN markets

Install

openclaw skills install futu-stock

futu-stock Skill

基于富途 OpenAPI 的股票行情 Skill，通过 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）→ 直接调用 get_stock_quote /    │
│     │   get_market_snapshot / get_history_kline 等                         │
│     └─ 无股票代码（如「港股 10–50 元的股票」）→ 使用 get_stock_filter 筛选     │
└─────────────────────────────────────────────────────────────────────────┘

二、环境检测与依赖处理

2.1 执行环境检测

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

输出示例：

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

2.2 依赖缺失时的安装

依赖检测方式安装命令
futu-mcp-serverwhich futu-mcp-serverpipx install futu-stock-mcp-server 或 pip install futu-stock-mcp-server
mcp 包python3 -c "import mcp"pip install mcp
Futu OpenDnetstat -an | grep 11111 或 lsof -i :11111见下方 OpenD 安装

2.3 OpenD 安装与启动

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

配置 FutuOpenD.xml：

  • login_account: 富途账号
  • login_pwd: 登录密码
  • api_port: 默认 11111
  • ip: 默认 127.0.0.1

启动：

# Linux/macOS
nohup ./FutuOpenD > opend.log 2>&1 &

# Windows
FutuOpenD.exe

2.4 调用时自动启动 OpenD

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

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

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

3.1 有明确股票代码

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

需求类型推荐工具示例
实时报价get_stock_quote 或 get_market_snapshot{"tool": "get_market_snapshot", "arguments": {"symbols": ["HK.00700"]}}
历史 K 线get_history_kline{"tool": "get_history_kline", "arguments": {"symbol": "HK.00700", "ktype": "K_DAY", "start": "2026-01-01", "end": "2026-02-25"}}
期权链get_option_chain{"tool": "get_option_chain", "arguments": {"symbol": "HK.00700", "start": "2026-04-01", "end": "2026-06-30"}}
需订阅的数据先 subscribe 再查见下方「需订阅的工具」

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

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

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

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

{
  "tool": "get_stock_filter",
  "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 深市创业板

base_filters 常用 field_name（参考富途 StockField）:

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

四、可用工具

行情

  • get_stock_quote: 报价
  • get_market_snapshot: 快照（含买卖盘）
  • get_cur_kline: 当前 K 线（需先 subscribe）
  • get_history_kline: 历史 K 线
  • get_rt_data: 实时数据（需 subscribe RT_DATA）
  • get_ticker: 逐笔（需 subscribe TICKER）
  • get_order_book: 买卖盘（需 subscribe ORDER_BOOK）
  • get_broker_queue: 经纪队列（需 subscribe BROKER）

订阅

  • subscribe: 订阅 QUOTE / ORDER_BOOK / TICKER / RT_DATA / BROKER / K_1M / K_DAY 等
  • unsubscribe: 取消订阅

期权

  • get_option_chain: 期权链
  • get_option_expiration_date: 到期日
  • get_option_condor: 鹰式策略
  • get_option_butterfly: 蝶式策略

账户

  • get_account_list: 账户列表
  • get_funds: 资金
  • get_positions: 持仓
  • get_max_power: 最大交易力
  • get_margin_ratio: 保证金比例

市场

  • get_market_state: 市场状态
  • get_security_info: 证券信息
  • get_security_list: 证券列表
  • get_stock_filter: 条件筛选（无代码时使用）

五、调用方式

执行工具

cd {baseDir}
python3 executor.py --call '{"tool": "get_market_snapshot", "arguments": {"symbols": ["HK.00700"]}}'

查看工具参数

cd {baseDir}
python3 executor.py --describe get_stock_filter

列出所有工具

cd {baseDir}
python3 executor.py --list

六、常见问题

Q1: futu-mcp-server 找不到

pipx install futu-stock-mcp-server
# 或
pip install futu-stock-mcp-server
which futu-mcp-server

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

# 检查端口
lsof -i :11111
# 或
netstat -an | grep 11111

# 未监听则启动 OpenD（见 2.3）
# 或配置 OPEND_PATH 让 executor 自动启动（见 2.4）

Q3: mcp 包未安装

pip install mcp

Q4: 股票代码格式错误

必须使用 {市场}.{代码}，例如：

  • 港股: HK.00700（不是 00700）
  • 美股: US.AAPL（不是 AAPL）

Q5: 需要订阅才能用的工具

get_cur_kline、get_rt_data、get_ticker、get_order_book、get_broker_queue 需先 subscribe：

# 1. 先订阅
python3 executor.py --call '{"tool": "subscribe", "arguments": {"symbols": ["HK.00700"], "sub_types": ["QUOTE", "K_DAY"]}}'

# 2. 再查询
python3 executor.py --call '{"tool": "get_cur_kline", "arguments": {"symbol": "HK.00700", "ktype": "K_DAY", "count": 100}}'

Q6: get_stock_filter 限频

  • 每 30 秒最多 10 次
  • 每页最多 200 条
  • 建议不超过 250 个筛选条件

Q7: 历史 K 线限制

  • 30 天内最多 30 只股票
  • 需合理控制 start 和 end 范围

七、配置

7.1 MCP 客户端配置（推荐）

在 MCP 客户端（如 CatPaw / Cursor）的 mcp.json 或 MCP Settings 中添加：

{
  "mcpServers": {
    "futu-stock": {
      "command": "futu-mcp-server",
      "env": {
        "FUTU_HOST": "127.0.0.1",
        "FUTU_PORT": "11111",
        "FUTU_TRADE_ENV": "REAL",
        "FUTU_TRD_MARKET": "HK",
        "FUTU_SECURITY_FIRM": "FUTUSECURITIES",
        "FUTU_ENABLE_POSITIONS": "0",
        "FUTU_ENABLE_TRADING": "0"
      }
    }
  }
}

环境变量说明：

变量默认值说明
FUTU_HOST127.0.0.1OpenD 监听地址
FUTU_PORT11111OpenD 监听端口
FUTU_TRADE_ENVSIMULATE交易环境：REAL（真实）/ SIMULATE（模拟）
FUTU_TRD_MARKETHK交易市场：HK / US / CN
FUTU_SECURITY_FIRMFUTUSECURITIES证券公司：FUTUSECURITIES（富途）/ FUTUINC（美国富途）等
FUTU_ENABLE_POSITIONS1是否启用持仓查询工具：1（开启）/ 0（关闭）
FUTU_ENABLE_TRADING0是否启用交易工具（下单/改单/撤单）：1（开启）/ 0（关闭，安全默认）
OPEND_PATH-可选，FutuOpenD 可执行文件所在目录，设置后可自动启动 OpenD

⚠️ 安全提示：FUTU_ENABLE_TRADING=0 默认关闭交易权限，如需 AI 代为下单请显式设为 1，并充分了解风险。

7.2 项目本地 .env 配置（从源码运行时使用）

复制 .env.example 为 .env 并按需修改：

cp .env.example .env

.env 示例内容：

# OpenD 连接
FUTU_HOST=127.0.0.1
FUTU_PORT=11111

# 功能开关
FUTU_ENABLE_TRADING=0
FUTU_ENABLE_POSITIONS=1

# 交易环境
FUTU_TRADE_ENV=SIMULATE
FUTU_SECURITY_FIRM=FUTUSECURITIES
FUTU_TRD_MARKET=HK

# 调试模式（不建议在 MCP 客户端中开启）
FUTU_DEBUG_MODE=0

7.3 OpenClaw Skill 配置

// ~/.openclaw/openclaw.json
{
  skills: {
    entries: {
      "futu-stock": {
        enabled: true,
        env: {
          FUTU_HOST: "127.0.0.1",
          FUTU_PORT: "11111",
          FUTU_TRADE_ENV: "REAL",          // REAL / SIMULATE
          FUTU_TRD_MARKET: "HK",           // HK / US / CN
          FUTU_SECURITY_FIRM: "FUTUSECURITIES",
          FUTU_ENABLE_POSITIONS: "1",      // 持仓查询
          FUTU_ENABLE_TRADING: "0",        // 交易操作（谨慎开启）
          OPEND_PATH: "/path/to/opend"     // 可选，自动启动 OpenD
        }
      }
    }
  }
}

八、使用流程速查

8.1 首次接入流程

第一步：确认 OpenD 运行
   └─ lsof -i :11111  → 看到 FutuOpenD 进程即正常

第二步：安装 MCP Server（如未安装）
   └─ pipx install futu-stock-mcp-server

第三步：配置 MCP 客户端
   └─ 将 7.1 节的 JSON 添加到 mcp.json / MCP Settings

第四步：验证连接
   └─ python3 executor.py --check-env

第五步：开始查询
   └─ 行情：get_stock_quote / get_market_snapshot
   └─ 账户：get_account_list / get_funds / get_positions

8.2 日常使用决策流程

  1. 先做环境检测：python3 executor.py --check-env
  2. 有缺失：按 2.2 安装缺失依赖
  3. 查账户信息：get_account_list → get_funds / get_positions
  4. 有股票代码：用 get_stock_quote / get_market_snapshot / get_history_kline 等
  5. 无股票代码：用 get_stock_filter 按条件筛选
  6. 需订阅：先 subscribe 再查
  7. 出错：按第六节常见问题排查

8.3 账户查询示例

# 查账户列表
python3 executor.py --call '{"tool": "get_account_list", "arguments": {}}'

# 查资产（模拟账户）
python3 executor.py --call '{"tool": "get_funds", "arguments": {}}'

# 查持仓（需 FUTU_ENABLE_POSITIONS=1）
python3 executor.py --call '{"tool": "get_positions", "arguments": {}}'

# 查持仓列表（带过滤）
python3 executor.py --call '{"tool": "get_position_list", "arguments": {"trd_env": "REAL"}}'

账户类工具的 trd_env 参数优先于环境变量 FUTU_TRADE_ENV，可临时切换真实/模拟环境。

本 Skill 通过 MCP 协议访问富途 OpenAPI，数据来自 https://github.com/shuizhengqi1/futu-stock-mcp-server

More in MCP Tools