Content
# Futu Stock MCP Server
[](https://www.python.org)
[](LICENSE)
[](https://openapi.futunn.com/futu-api-doc/)
基于[模型上下文协议(MCP)](https://github.com/cursor-ai/model-context-protocol)的富途证券行情交易接口服务器。将富途OpenAPI功能以标准化的MCP协议提供给AI模型使用，支持行情订阅、数据查询等功能。
## 🌟 特性
- 🔌 完全兼容 MCP 2.0 协议标准
- 📊 支持港股、美股、A股等市场的实时行情
- 🔄 支持实时数据订阅和推送
- 📈 支持K线、逐笔、买卖盘等多维度数据
- 🔒 安全的API调用和数据访问机制
- 🛠 提供完整的开发工具和示例代码
## ⚠️ 前置要求
在使用本项目之前，您需要：
1. 拥有富途证券账户并开通OpenAPI权限
2. 安装并运行富途的OpenD网关程序（[官方文档](https://openapi.futunn.com/futu-api-doc/intro/intro.html)）
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 安装（推荐）
```bash
# 安装 pipx（如果还没有安装）
brew install pipx # macOS
# 或者 pip install --user pipx # 其他系统
# 安装包
pipx install futu-stock-mcp-server
# 运行服务器
futu-mcp-server
```
> **为什么使用 pipx？**
> - pipx 专门用于安装 Python 应用程序到全局环境
> - 自动管理独立的虚拟环境，避免依赖冲突
> - 命令直接可用，无需激活虚拟环境
### 方式二：通过 Docker 运行
```bash
# 拉取镜像
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:
```bash
git clone https://github.com/yourusername/futu-stock-mcp-server.git
cd futu-stock-mcp-server
```
2. Install uv:
```bash
# 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:
```bash
# Create virtual environment
uv venv
# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate
```
4. Install dependencies:
```bash
# Install in editable mode
uv pip install -e .
```
5. (可选) 如需从源码直接运行，通过环境变量配置服务：
```bash
export FUTU_HOST=127.0.0.1
export FUTU_PORT=11111
```
> **推荐方式**：在 MCP 客户端配置文件中使用 `env` 字段注入，无需创建 `.env` 文件，见下方 [MCP Server 配置](#-mcp-server-配置) 章节。
## Development
### Managing Dependencies
Add new dependencies to `pyproject.toml`:
```toml
[project]
dependencies = [
# ... existing dependencies ...
"new-package>=1.0.0",
]
```
Then update your environment:
```bash
uv pip install -e .
```
### Code Style
This project uses Ruff for code linting and formatting. The configuration is in `pyproject.toml`:
```toml
[tool.ruff]
line-length = 100
target-version = "py38"
[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "B", "UP"]
```
Run linting:
```bash
uv pip install ruff
ruff check .
```
Run formatting:
```bash
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` 文件）：
```json
{
"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` 命令启动**（适用于源码开发场景）：
```json
{
"mcpServers": {
"futu-stock": {
"command": "python",
"args": ["-m", "futu_stock_mcp_server.server"],
"env": {
"FUTU_HOST": "127.0.0.1",
"FUTU_PORT": "11111"
}
}
}
}
```
4. **故障排除配置**：
如果上述配置不工作，可以尝试使用完整路径：
```json
{
"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 客户端
```python
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 客户端
```javascript
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. 启动服务器（独立运行）
```bash
# 通过 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` 找不到
```bash
# 确保已正确安装
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 失败
```bash
# 检查 OpenD 是否运行
netstat -an | grep 11111
# 检查环境变量
echo $FUTU_HOST
echo $FUTU_PORT
```
#### 4. Claude Desktop 无法识别服务器
- 确保配置文件路径正确
- 检查 JSON 格式是否有效
- 重启 Claude Desktop
- 查看 Claude Desktop 的日志文件
#### 5. 权限问题
```bash
# 确保有执行权限
chmod +x ~/.local/bin/futu-mcp-server
# 或者使用完整路径
python -m futu_stock_mcp_server.server
```
### 日志调试
本项目已根据 [MCP 官方文档](https://github.com/modelcontextprotocol/python-sdk) 的最佳实践配置了日志系统：
#### MCP 兼容的日志配置
- **文件日志**: 所有日志写入 `logs/futu_server.log`，自动轮转和清理
- **MCP Context 日志**: 工具执行期间通过 MCP Context 发送日志给客户端
- **stdout 保护**: 确保 stdout 仅用于 MCP JSON 通信，避免污染
#### 调试模式（仅开发时使用）
```bash
# 启用调试模式（会向 stderr 输出日志）
export FUTU_DEBUG_MODE=1
futu-mcp-server
```
**注意**: 在 MCP 客户端中不要启用调试模式，因为它会向 stderr 输出日志。
#### 日志文件位置
- 主日志文件：`./logs/futu_server.log`
- 自动轮转：500 MB 后轮转
- 自动清理：保留 10 天
详细的日志配置说明请参考 [docs/LOGGING.md](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` (optional): List of accumulate filters
```python
{
"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` (optional): List of financial filters
```python
{
"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` (optional): Market code (e.g. "HK.Motherboard", "US.NASDAQ")
- `page` (optional): Page number, starting from 1 (default: 1)
- `page_size` (optional): Number of results per page, max 200 (default: 200)
Supported Market Codes:
- `HK.Motherboard`: Hong Kong Main Board
- `HK.GEM`: Hong Kong GEM
- `HK.BK1911`: H-Share Main Board
- `HK.BK1912`: H-Share GEM
- `US.NYSE`: NYSE
- `US.AMEX`: AMEX
- `US.NASDAQ`: NASDAQ
- `SH.3000000`: Shanghai Main Board
- `SZ.3000001`: Shenzhen Main Board
- `SZ.3000004`: Shenzhen ChiNext
Example:
```python
# 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)
```
Notes:
- Limited to 10 requests per 30 seconds
- Each page returns maximum 200 results
- Recommended to use no more than 250 filter conditions
- Maximum 10 accumulate conditions of the same type
- Dynamic data sorting (like current price) may change between pages
- Cannot compare different types of indicators (e.g. MA5 vs EMA10)
## Resources
### Market Data
- `market://{symbol}`: Get market data for a symbol
- `kline://{symbol}/{ktype}`: Get K-line data for a symbol
## Prompts
### Analysis
- `market_analysis`: Create a market analysis prompt
- `option_strategy`: Create an option strategy analysis prompt
## Error Handling
The server follows the MCP 2.0 error response format:
```json
{
"jsonrpc": "2.0",
"id": "request_id",
"error": {
"code": -32000,
"message": "Error message",
"data": null
}
}
```
## Security
- The server uses secure WebSocket connections
- All API calls are authenticated through the Futu OpenAPI
- Environment variables are used for sensitive configuration
## Development
### Adding New Tools
To add a new tool, use the `@mcp.tool()` decorator:
```python
@mcp.tool()
async def new_tool(param1: str, param2: int) -> Dict[str, Any]:
"""Tool description"""
# Implementation
return result
```
### Adding New Resources
To add a new resource, use the `@mcp.resource()` decorator:
```python
@mcp.resource("resource://{param1}/{param2}")
async def new_resource(param1: str, param2: str) -> Dict[str, Any]:
"""Resource description"""
# Implementation
return result
```
### Adding New Prompts
To add a new prompt, use the `@mcp.prompt()` decorator:
```python
@mcp.prompt()
async def new_prompt(param1: str) -> str:
"""Prompt description"""
return f"Prompt template with {param1}"
```
## License
MIT License
## Available MCP Functions
### Market Data Functions
#### get_stock_quote
Get stock quote data for given symbols.
```python
symbols = ["HK.00700", "US.AAPL", "SH.600519"]
result = await session.call_tool("get_stock_quote", {"symbols": symbols})
```
Returns quote data including price, volume, turnover, etc.
#### get_market_snapshot
Get market snapshot for given symbols.
```python
symbols = ["HK.00700", "US.AAPL", "SH.600519"]
result = await session.call_tool("get_market_snapshot", {"symbols": symbols})
```
Returns comprehensive market data including price, volume, bid/ask prices, etc.
#### get_cur_kline
Get current K-line data.
```python
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
Get historical K-line data.
```python
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
Get real-time trading data.
```python
result = await session.call_tool("get_rt_data", {"symbol": "HK.00700"})
```
#### get_ticker
Get ticker data (detailed trades).
```python
result = await session.call_tool("get_ticker", {"symbol": "HK.00700"})
```
#### get_order_book
Get order book data.
```python
result = await session.call_tool("get_order_book", {"symbol": "HK.00700"})
```
#### get_broker_queue
Get broker queue data.
```python
result = await session.call_tool("get_broker_queue", {"symbol": "HK.00700"})
```
### Subscription Functions
#### subscribe
Subscribe to real-time data.
```python
result = await session.call_tool("subscribe", {
"symbols": ["HK.00700", "US.AAPL"],
"sub_types": ["QUOTE", "TICKER", "K_1M"]
})
```
Subscription types:
- "QUOTE": Basic quote
- "ORDER_BOOK": Order book
- "TICKER": Trades
- "RT_DATA": Real-time data
- "BROKER": Broker queue
- "K_1M" to "K_MON": K-line data
#### unsubscribe
Unsubscribe from real-time data.
```python
result = await session.call_tool("unsubscribe", {
"symbols": ["HK.00700", "US.AAPL"],
"sub_types": ["QUOTE", "TICKER"]
})
```
### Options Functions
#### get_option_chain
Get option chain data.
```python
result = await session.call_tool("get_option_chain", {
"symbol": "HK.00700",
"start": "2024-04-01",
"end": "2024-06-30"
})
```
#### get_option_expiration_date
Get option expiration dates.
```python
result = await session.call_tool("get_option_expiration_date", {
"symbol": "HK.00700"
})
```
#### get_option_condor
Get option condor strategy data.
```python
result = await session.call_tool("get_option_condor", {
"symbol": "HK.00700",
"expiry": "2024-06-30",
"strike_price": 350.0
})
```
#### get_option_butterfly
Get option butterfly strategy data.
```python
result = await session.call_tool("get_option_butterfly", {
"symbol": "HK.00700",
"expiry": "2024-06-30",
"strike_price": 350.0
})
```
### Account Functions
#### get_account_list
Get account list.
```python
result = await session.call_tool("get_account_list", {"random_string": "dummy"})
```
#### get_funds
Get account funds information.
```python
result = await session.call_tool("get_funds", {"random_string": "dummy"})
```
#### get_positions
Get account positions.
```python
result = await session.call_tool("get_positions", {"random_string": "dummy"})
```
#### get_max_power
Get maximum trading power.
```python
result = await session.call_tool("get_max_power", {"random_string": "dummy"})
```
#### get_margin_ratio
Get margin ratio for a security.
```python
result = await session.call_tool("get_margin_ratio", {"symbol": "HK.00700"})
```
### Market Information Functions
#### get_market_state
Get market state.
```python
result = await session.call_tool("get_market_state", {"market": "HK"})
```
Available markets: "HK", "US", "SH", "SZ"
#### get_security_info
Get security information.
```python
result = await session.call_tool("get_security_info", {
"market": "HK",
"code": "00700"
})
```
#### get_security_list
Get security list for a market.
```python
result = await session.call_tool("get_security_list", {"market": "HK"})
```
#### get_stock_filter
Get filtered stock list based on conditions.
```python
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
})
```
### Time Function
#### get_current_time
Get current server time.
```python
result = await session.call_tool("get_current_time", {"random_string": "dummy"})
```
Returns timestamp, formatted datetime, date, time and timezone.
