Futu Stock MCP Server

Futu Stock MCP Server

基于模型上下文协议(MCP)的富途证券行情交易接口服务器。将富途OpenAPI功能以标准化的MCP协议提供给AI模型使用，支持行情订阅、数据查询等功能。

🌟 特性

• 🔌 完全兼容 MCP 2.0 协议标准
• 📊 支持港股、美股、A股等市场的实时行情
• 🔄 支持实时数据订阅和推送
• 📈 支持K线、逐笔、买卖盘等多维度数据
• 🔒 安全的API调用和数据访问机制
• 🛠 提供完整的开发工具和示例代码

⚠️ 前置要求

在使用本项目之前，您需要：

1. 拥有富途证券账户并开通OpenAPI权限
2. 安装并运行富途的OpenD网关程序（官方文档）
3. 根据您的需求订阅相应的行情权限

🔒 安全提示

• 请勿在代码中硬编码任何账号密码信息
• 确保.env文件已添加到.gitignore中
• 妥善保管您的API访问凭证
• 遵守富途OpenAPI的使用条款和限制

📝 免责声明

本项目是一个开源工具，旨在简化富途OpenAPI的接入流程。使用本项目时请注意：

1. 遵守相关法律法规和富途OpenAPI的使用条款
2. 自行承担使用本项目进行交易的风险
3. 本项目不提供任何投资建议
4. 使用本项目前请确保您已获得所需的行情权限

Features

• Standard MCP 2.0 protocol compliance
• Comprehensive Futu API coverage
• Real-time data subscription support
• Market data access
• Derivatives information
• Account query capabilities
• Resource-based data access
• Interactive prompts for analysis

Prerequisites

• Python 3.10+
• Futu OpenAPI SDK
• Model Context Protocol SDK
• uv (recommended)

🚀 快速开始

方式一：通过 pipx 安装（推荐）

# 安装 pipx（如果还没有安装）
brew install pipx  # macOS
# 或者 pip install --user pipx  # 其他系统

# 安装包
pipx install futu-stock-mcp-server

# 运行服务器
futu-mcp-server

为什么使用 pipx？

• pipx 专门用于安装 Python 应用程序到全局环境
• 自动管理独立的虚拟环境，避免依赖冲突
• 命令直接可用，无需激活虚拟环境

方式二：通过 Docker 运行

# 拉取镜像
docker pull your-registry/futu-stock-mcp-server:latest

# 运行容器
docker run -d \
  --name futu-mcp-server \
  -p 8000:8000 \
  -e FUTU_HOST=127.0.0.1 \
  -e FUTU_PORT=11111 \
  your-registry/futu-stock-mcp-server:latest

方式三：从源码安装

1. Clone the repository:

git clone https://github.com/yourusername/futu-stock-mcp-server.git
cd futu-stock-mcp-server

2. Install uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Create and activate a virtual environment:

# Create virtual environment
uv venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

4. Install dependencies:

# Install in editable mode
uv pip install -e .

5. (可选) 如需从源码直接运行，通过环境变量配置服务：

export FUTU_HOST=127.0.0.1
export FUTU_PORT=11111

推荐方式：在 MCP 客户端配置文件中使用 env 字段注入，无需创建 .env 文件，见下方 MCP Server 配置 章节。

Development

Managing Dependencies

Add new dependencies to pyproject.toml:

[project]
dependencies = [
    # ... existing dependencies ...
    "new-package>=1.0.0",
]

Then update your environment:

uv pip install -e .

Code Style

This project uses Ruff for code linting and formatting. The configuration is in pyproject.toml:

[tool.ruff]
line-length = 100
target-version = "py38"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "B", "UP"]

Run linting:

uv pip install ruff
ruff check .

Run formatting:

ruff format .

🔧 MCP Server 配置

在 Claude Desktop 中配置

1. 找到配置文件位置：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 添加服务器配置（所有参数均通过 env 字段注入，无需 .env 文件）：

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

3. 使用 python 命令启动（适用于源码开发场景）：

{
  "mcpServers": {
    "futu-stock": {
      "command": "python",
      "args": ["-m", "futu_stock_mcp_server.server"],
      "env": {
        "FUTU_HOST": "127.0.0.1",
        "FUTU_PORT": "11111"
      }
    }
  }
}

4. 故障排除配置： 如果上述配置不工作，可以尝试使用完整路径：

{
  "mcpServers": {
    "futu-stock": {
      "command": "/Users/your-username/.local/bin/futu-mcp-server",
      "env": {
        "FUTU_HOST": "127.0.0.1",
        "FUTU_PORT": "11111"
      }
    }
  }
}

提示：使用 which futu-mcp-server 命令查看完整路径

在其他 MCP 客户端中配置

使用 Python MCP 客户端

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="futu-mcp-server",
        env={
            "FUTU_HOST": "127.0.0.1",
            "FUTU_PORT": "11111"
        }
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the connection
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print("Available tools:", [tool.name for tool in tools.tools])

使用 Node.js MCP 客户端

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "futu-mcp-server",
  env: {
    FUTU_HOST: "127.0.0.1",
    FUTU_PORT: "11111"
  }
});

const client = new Client({
  name: "futu-stock-client",
  version: "1.0.0"
}, {
  capabilities: {}
});

await client.connect(transport);

📋 使用方法

1. 启动服务器（独立运行）

# 通过 pip 安装后
futu-mcp-server

# 或从源码运行
python -m futu_stock_mcp_server.server

2. 环境变量配置

推荐在 MCP 客户端的 env 字段中直接配置，无需 .env 文件：

环境变量	说明	默认值
FUTU_HOST	OpenD 地址	127.0.0.1
FUTU_PORT	OpenD 端口	11111
FUTU_TRADE_ENV	交易环境 (SIMULATE/REAL)	SIMULATE
FUTU_SECURITY_FIRM	券商 (FUTUSECURITIES/FUTUINC)	FUTUSECURITIES
FUTU_TRD_MARKET	交易市场 (HK/US)	HK
FUTU_DEBUG_MODE	调试日志开关 (0/1)	0

3. 验证连接

启动服务器后，你应该看到类似的日志：

2024-10-02 14:20:52 | INFO | Initializing Futu connection...
2024-10-02 14:20:52 | INFO | Successfully initialized Futu connection
2024-10-02 14:20:52 | INFO | Starting MCP server in stdio mode...
2024-10-02 14:20:52 | INFO | Press Ctrl+C to stop the server

4. 在 AI 工具中使用

配置完成后，重启 Claude Desktop 或其他 MCP 客户端，你就可以：

• 查询股票实时行情
• 获取历史K线数据
• 订阅股票数据推送
• 查询账户信息
• 执行交易操作（需要交易权限）

🔧 故障排除

常见问题

1. 命令 futu-mcp-server 找不到

# 确保已正确安装
pipx install futu-stock-mcp-server

# 检查命令是否可用
which futu-mcp-server

# 如果还是找不到，检查 PATH
echo $PATH | grep -o '[^:]*\.local/bin[^:]*'

2. Ctrl+C 无法退出服务器

• 新版本已修复此问题
• 如果仍然遇到，可以使用 kill -9 <pid> 强制终止

3. 连接富途 OpenD 失败

# 检查 OpenD 是否运行
netstat -an | grep 11111

# 检查环境变量
echo $FUTU_HOST
echo $FUTU_PORT

4. Claude Desktop 无法识别服务器

• 确保配置文件路径正确
• 检查 JSON 格式是否有效
• 重启 Claude Desktop
• 查看 Claude Desktop 的日志文件

5. 权限问题

# 确保有执行权限
chmod +x ~/.local/bin/futu-mcp-server

# 或者使用完整路径
python -m futu_stock_mcp_server.server

日志调试

本项目已根据 MCP 官方文档 的最佳实践配置了日志系统：

MCP 兼容的日志配置

• 文件日志: 所有日志写入 logs/futu_server.log，自动轮转和清理
• MCP Context 日志: 工具执行期间通过 MCP Context 发送日志给客户端
• stdout 保护: 确保 stdout 仅用于 MCP JSON 通信，避免污染

调试模式（仅开发时使用）

# 启用调试模式（会向 stderr 输出日志）
export FUTU_DEBUG_MODE=1
futu-mcp-server

注意: 在 MCP 客户端中不要启用调试模式，因为它会向 stderr 输出日志。

日志文件位置

• 主日志文件：./logs/futu_server.log
• 自动轮转：500 MB 后轮转
• 自动清理：保留 10 天

详细的日志配置说明请参考 docs/LOGGING.md。 tools = await session.list_tools()

        # Call a tool
        result = await session.call_tool(
            "get_stock_quote",
            arguments={"symbols": ["HK.00700"]}
        )
        
        # Access a resource
        content, mime_type = await session.read_resource(
            "market://HK.00700"
        )
        
        # Get a prompt
        prompt = await session.get_prompt(
            "market_analysis",
            arguments={"symbol": "HK.00700"}
        )

if name == "main": import asyncio asyncio.run(main())

## Changelog

Latest updates (`2026-03-02`) - v0.1.5:
- **环境变量优先配置**：`FUTU_HOST` / `FUTU_PORT` 现在直接通过 MCP 客户端 `env` 字段注入，无需 `.env` 文件。
- 移除 `python-dotenv` 导入，简化依赖。
- 新增 `python -m` 启动方式的配置示例。

Previous updates (`2026-03-02`) - v0.1.4:
- Added trading MCP tools: `unlock_trade`, `place_order`, `modify_order`, `cancel_order`, `cancel_all_orders`, order/deal query tools, fee/cashflow tools.
- Added position and trade feature switches: `FUTU_ENABLE_POSITIONS`, `FUTU_ENABLE_TRADING`.
- Added official Futu API to MCP mapping doc: [docs/FUTU_API_MCP_COVERAGE.md](docs/FUTU_API_MCP_COVERAGE.md).
- Kept backward compatibility: existing MCP tool names and argument contracts were not changed.

Full history: [CHANGELOG.md](CHANGELOG.md)

## Available API Methods

Full mapping document (official Futu API -> MCP tools): [docs/FUTU_API_MCP_COVERAGE.md](docs/FUTU_API_MCP_COVERAGE.md)

### Market Data Tools
- `get_stock_quote`: Get stock quote data
- `get_market_snapshot`: Get market snapshot
- `get_cur_kline`: Get current K-line data
- `get_history_kline`: Get historical K-line data
- `get_rt_data`: Get real-time data
- `get_ticker`: Get ticker data
- `get_order_book`: Get order book data
- `get_broker_queue`: Get broker queue data

### Subscription Tools
- `subscribe`: Subscribe to real-time data
- `unsubscribe`: Unsubscribe from real-time data

### Derivatives Tools
- `get_option_chain`: Get option chain data
- `get_option_expiration_date`: Get option expiration dates
- `get_option_condor`: Get option condor strategy data
- `get_option_butterfly`: Get option butterfly strategy data

### Account Query Tools
- `get_account_list`: Get account list
- `get_funds`: Get account funds information
- `get_positions`: Get account positions
- `get_position_list`: Get account positions with filters
- `get_max_power`: Get account buying power
- `get_margin_ratio`: Get margin ratio for a security

### Trading Tools
- `unlock_trade`: Unlock trade operations
- `place_order`: Place order
- `modify_order`: Modify order
- `cancel_order`: Cancel one order
- `cancel_all_orders`: Cancel all cancellable orders
- `get_order_list`: Query current order list
- `get_history_order_list`: Query historical orders
- `get_deal_list`: Query current deals
- `get_history_deal_list`: Query historical deals
- `get_order_fee`: Query order fee details
- `get_acc_cash_flow`: Query cash flow details
- `get_acc_trading_info`: Query trade capability/pre-check

### Market Information Tools
- `get_market_state`: Get market state
- `get_security_info`: Get security information
- `get_security_list`: Get security list

### Stock Filter Commands

#### get_stock_filter
Filter stocks based on various conditions.

Parameters:
- `base_filters` (optional): List of basic stock filters
  ```python
  {
      "field_name": int,  # StockField enum value
      "filter_min": float,  # Optional minimum value
      "filter_max": float,  # Optional maximum value
      "is_no_filter": bool,  # Optional, whether to skip filtering
      "sort_dir": int  # Optional, sort direction
  }

• accumulate_filters（可选）：累积指标筛选条件列表

  {
      "field_name": int,  # AccumulateField enum value
      "filter_min": float,
      "filter_max": float,
      "is_no_filter": bool,
      "sort_dir": int,
      "days": int  # Required, number of days to accumulate
  }
  

• financial_filters（可选）：财务指标筛选条件列表

  {
      "field_name": int,  # FinancialField enum value
      "filter_min": float,
      "filter_max": float,
      "is_no_filter": bool,
      "sort_dir": int,
      "quarter": int  # Required, financial quarter
  }
  

• market（可选）：市场代码（例如 "HK.Motherboard"、"US.NASDAQ"）
• page（可选）：页码，从 1 开始（默认值：1）
• page_size（可选）：每页结果数，最多 200（默认值：200）

支持的市场代码：

• HK.Motherboard：香港主板
• HK.GEM：香港创业板
• HK.BK1911：H 股主板
• HK.BK1912：H 股创业板
• US.NYSE：NYSE
• US.AMEX：AMEX
• US.NASDAQ：NASDAQ
• SH.3000000：上海主板
• SZ.3000001：深圳主板
• SZ.3000004：深圳创业板

示例：

# Get stocks with price between 10 and 50 HKD in Hong Kong Main Board
filters = {
    "base_filters": [{
        "field_name": 5,  # Current price
        "filter_min": 10.0,
        "filter_max": 50.0
    }],
    "market": "HK.Motherboard"
}
result = await client.get_stock_filter(**filters)

注意：

• 30 秒内最多请求 10 次
• 每页最多返回 200 条结果
• 建议筛选条件不超过 250 个
• 同一类型的累积条件最多 10 个
• 动态数据排序（如当前价格）可能会在不同页面间变化
• 无法比较不同类型的指标（例如 MA5 与 EMA10）

资源

市场数据

• market://{symbol}：获取指定代码的市场数据
• kline://{symbol}/{ktype}：获取指定代码的 K 线数据

提示词

分析

• market_analysis：创建市场分析提示词
• option_strategy：创建期权策略分析提示词

错误处理

服务遵循 MCP 2.0 错误响应格式：

{
    "jsonrpc": "2.0",
    "id": "request_id",
    "error": {
        "code": -32000,
        "message": "Error message",
        "data": null
    }
}

安全

• 服务使用安全的 WebSocket 连接
• 所有 API 调用均通过 Futu OpenAPI 进行身份验证
• 使用环境变量存储敏感配置

开发

添加新工具

要添加新工具，请使用 @mcp.tool() 装饰器：

@mcp.tool()
async def new_tool(param1: str, param2: int) -> Dict[str, Any]:
    """Tool description"""
    # Implementation
    return result

添加新资源

要添加新资源，请使用 @mcp.resource() 装饰器：

@mcp.resource("resource://{param1}/{param2}")
async def new_resource(param1: str, param2: str) -> Dict[str, Any]:
    """Resource description"""
    # Implementation
    return result

添加新提示词

要添加新提示词，请使用 @mcp.prompt() 装饰器：

@mcp.prompt()
async def new_prompt(param1: str) -> str:
    """Prompt description"""
    return f"Prompt template with {param1}"

许可证

MIT License

可用的 MCP 函数

市场数据函数

get_stock_quote

获取指定代码的股票报价数据。

symbols = ["HK.00700", "US.AAPL", "SH.600519"]
result = await session.call_tool("get_stock_quote", {"symbols": symbols})

返回包含价格、成交量、成交额等信息的报价数据。

get_market_snapshot

获取指定代码的市场快照。

symbols = ["HK.00700", "US.AAPL", "SH.600519"]
result = await session.call_tool("get_market_snapshot", {"symbols": symbols})

返回包含价格、成交量、买卖价等信息的综合市场数据。

get_cur_kline

获取当前 K 线数据。

result = await session.call_tool("get_cur_kline", {
    "symbol": "HK.00700",
    "ktype": "K_1M",  # K_1M, K_5M, K_15M, K_30M, K_60M, K_DAY, K_WEEK, K_MON
    "count": 100
})

get_history_kline

获取历史 K 线数据。

result = await session.call_tool("get_history_kline", {
    "symbol": "HK.00700",
    "ktype": "K_DAY",
    "start": "2024-01-01",
    "end": "2024-03-31"
})

get_rt_data

获取实时交易数据。

result = await session.call_tool("get_rt_data", {"symbol": "HK.00700"})

get_ticker

获取逐笔成交数据（详细交易记录）。

result = await session.call_tool("get_ticker", {"symbol": "HK.00700"})

get_order_book

获取订单簿数据。

result = await session.call_tool("get_order_book", {"symbol": "HK.00700"})

get_broker_queue

获取经纪商队列数据。

result = await session.call_tool("get_broker_queue", {"symbol": "HK.00700"})

订阅函数

subscribe

订阅实时数据。

result = await session.call_tool("subscribe", {
    "symbols": ["HK.00700", "US.AAPL"],
    "sub_types": ["QUOTE", "TICKER", "K_1M"]
})

订阅类型：

• "QUOTE"：基本报价
• "ORDER_BOOK"：订单簿
• "TICKER"：逐笔成交
• "RT_DATA"：实时数据
• "BROKER"：经纪商队列
• "K_1M" 到 "K_MON"：K 线数据

unsubscribe

取消订阅实时数据。

result = await session.call_tool("unsubscribe", {
    "symbols": ["HK.00700", "US.AAPL"],
    "sub_types": ["QUOTE", "TICKER"]
})

期权函数

get_option_chain

获取期权链数据。

result = await session.call_tool("get_option_chain", {
    "symbol": "HK.00700",
    "start": "2024-04-01",
    "end": "2024-06-30"
})

get_option_expiration_date

获取期权到期日。

result = await session.call_tool("get_option_expiration_date", {
    "symbol": "HK.00700"
})

get_option_condor

获取期权秃鹰策略数据。

result = await session.call_tool("get_option_condor", {
    "symbol": "HK.00700",
    "expiry": "2024-06-30",
    "strike_price": 350.0
})

get_option_butterfly

获取期权蝶式策略数据。

result = await session.call_tool("get_option_butterfly", {
    "symbol": "HK.00700",
    "expiry": "2024-06-30",
    "strike_price": 350.0
})

账户函数

get_account_list

获取账户列表。

result = await session.call_tool("get_account_list", {"random_string": "dummy"})

get_funds

获取账户资金信息。

result = await session.call_tool("get_funds", {"random_string": "dummy"})

get_positions

获取账户持仓。

result = await session.call_tool("get_positions", {"random_string": "dummy"})

get_max_power

获取最大交易能力。

result = await session.call_tool("get_max_power", {"random_string": "dummy"})

get_margin_ratio

获取证券的保证金比例。

result = await session.call_tool("get_margin_ratio", {"symbol": "HK.00700"})

市场信息函数

get_market_state

获取市场状态。

result = await session.call_tool("get_market_state", {"market": "HK"})

可用市场：“HK”“US”“SH”“SZ”

get_security_info

获取证券信息。

result = await session.call_tool("get_security_info", {
    "market": "HK",
    "code": "00700"
})

get_security_list

获取市场的证券列表。

result = await session.call_tool("get_security_list", {"market": "HK"})

get_stock_filter

根据条件筛选股票列表。

result = await session.call_tool("get_stock_filter", {
    "market": "HK.Motherboard",
    "base_filters": [{
        "field_name": 1,  # Price
        "filter_min": 10.0,
        "filter_max": 50.0,
        "sort_dir": 1  # Ascending
    }],
    "page": 1,
    "page_size": 50
})

时间函数

get_current_time

获取当前服务端时间。

result = await session.call_tool("get_current_time", {"random_string": "dummy"})

返回时间戳、格式化日期时间、日期、时间和时区。