Futu Stock
STDIOMCP server providing Futu Securities API integration for stock trading and market data
MCP server providing Futu Securities API integration for stock trading and market data
基于模型上下文协议(MCP)的富途证券行情交易接口服务器。将富途OpenAPI功能以标准化的MCP协议提供给AI模型使用，支持行情订阅、数据查询等功能。
在使用本项目之前，您需要：
.env文件已添加到.gitignore中本项目是一个开源工具，旨在简化富途OpenAPI的接入流程。使用本项目时请注意：
# 安装 pipx（如果还没有安装） brew install pipx # macOS # 或者 pip install --user pipx # 其他系统 # 安装包 pipx install futu-stock-mcp-server # 运行服务器 futu-mcp-server
为什么使用 pipx？
- pipx 专门用于安装 Python 应用程序到全局环境
- 自动管理独立的虚拟环境，避免依赖冲突
- 命令直接可用，无需激活虚拟环境
# 拉取镜像 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
git clone https://github.com/yourusername/futu-stock-mcp-server.git cd futu-stock-mcp-server
# macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Create virtual environment uv venv # Activate virtual environment # On macOS/Linux: source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install in editable mode uv pip install -e .
cp .env.example .env
Edit the .env file with your server settings:
HOST=0.0.0.0
PORT=8000
FUTU_HOST=127.0.0.1
FUTU_PORT=11111
Add new dependencies to pyproject.toml:
[project] dependencies = [ # ... existing dependencies ... "new-package>=1.0.0", ]
Then update your environment:
uv pip install -e .
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 .
找到配置文件位置：
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json添加服务器配置：
{ "mcpServers": { "futu-stock": { "command": "futu-mcp-server", "env": { "FUTU_HOST": "127.0.0.1", "FUTU_PORT": "11111" } } } }
{ "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命令查看完整路径
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])
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);
# 通过 pip 安装后 futu-mcp-server # 或从源码运行 python -m futu_stock_mcp_server.server
创建 .env 文件或设置环境变量：
FUTU_HOST=127.0.0.1 FUTU_PORT=11111 LOG_LEVEL=INFO
启动服务器后，你应该看到类似的日志：
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
配置完成后，重启 Claude Desktop 或其他 MCP 客户端，你就可以：
futu-mcp-server 找不到# 确保已正确安装 pipx install futu-stock-mcp-server # 检查命令是否可用 which futu-mcp-server # 如果还是找不到，检查 PATH echo $PATH | grep -o '[^:]*\.local/bin[^:]*'
kill -9 <pid> 强制终止# 检查 OpenD 是否运行 netstat -an | grep 11111 # 检查环境变量 echo $FUTU_HOST echo $FUTU_PORT
# 确保有执行权限 chmod +x ~/.local/bin/futu-mcp-server # 或者使用完整路径 python -m futu_stock_mcp_server.server
本项目已根据 MCP 官方文档 的最佳实践配置了日志系统：
logs/futu_server.log，自动轮转和清理# 启用调试模式（会向 stderr 输出日志） export FUTU_DEBUG_MODE=1 futu-mcp-server
注意: 在 MCP 客户端中不要启用调试模式，因为它会向 stderr 输出日志。
./logs/futu_server.log详细的日志配置说明请参考 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())
## Available API Methods
### 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_asset_info`: Get asset information
- `get_asset_allocation`: Get asset allocation information
### 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
{ "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
{ "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 BoardHK.GEM: Hong Kong GEMHK.BK1911: H-Share Main BoardHK.BK1912: H-Share GEMUS.NYSE: NYSEUS.AMEX: AMEXUS.NASDAQ: NASDAQSH.3000000: Shanghai Main BoardSZ.3000001: Shenzhen Main BoardSZ.3000004: Shenzhen ChiNextExample:
# 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:
market://{symbol}: Get market data for a symbolkline://{symbol}/{ktype}: Get K-line data for a symbolmarket_analysis: Create a market analysis promptoption_strategy: Create an option strategy analysis promptThe server follows the MCP 2.0 error response format:
{ "jsonrpc": "2.0", "id": "request_id", "error": { "code": -32000, "message": "Error message", "data": null } }
To add a new tool, use the @mcp.tool() decorator:
@mcp.tool() async def new_tool(param1: str, param2: int) -> Dict[str, Any]: """Tool description""" # Implementation return result
To add a new resource, use the @mcp.resource() decorator:
@mcp.resource("resource://{param1}/{param2}") async def new_resource(param1: str, param2: str) -> Dict[str, Any]: """Resource description""" # Implementation return result
To add a new prompt, use the @mcp.prompt() decorator:
@mcp.prompt() async def new_prompt(param1: str) -> str: """Prompt description""" return f"Prompt template with {param1}"
MIT License
Get stock quote data for given symbols.
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 for given symbols.
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 current K-line data.
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 historical K-line data.
result = await session.call_tool("get_history_kline", { "symbol": "HK.00700", "ktype": "K_DAY", "start": "2024-01-01", "end": "2024-03-31" })
Get real-time trading data.
result = await session.call_tool("get_rt_data", {"symbol": "HK.00700"})
Get ticker data (detailed trades).
result = await session.call_tool("get_ticker", {"symbol": "HK.00700"})
Get order book data.
result = await session.call_tool("get_order_book", {"symbol": "HK.00700"})
Get broker queue data.
result = await session.call_tool("get_broker_queue", {"symbol": "HK.00700"})
Subscribe to real-time data.
result = await session.call_tool("subscribe", { "symbols": ["HK.00700", "US.AAPL"], "sub_types": ["QUOTE", "TICKER", "K_1M"] })
Subscription types:
Unsubscribe from real-time data.
result = await session.call_tool("unsubscribe", { "symbols": ["HK.00700", "US.AAPL"], "sub_types": ["QUOTE", "TICKER"] })
Get option chain data.
result = await session.call_tool("get_option_chain", { "symbol": "HK.00700", "start": "2024-04-01", "end": "2024-06-30" })
Get option expiration dates.
result = await session.call_tool("get_option_expiration_date", { "symbol": "HK.00700" })
Get option condor strategy data.
result = await session.call_tool("get_option_condor", { "symbol": "HK.00700", "expiry": "2024-06-30", "strike_price": 350.0 })
Get option butterfly strategy data.
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 account funds information.
result = await session.call_tool("get_funds", {"random_string": "dummy"})
Get account positions.
result = await session.call_tool("get_positions", {"random_string": "dummy"})
Get maximum trading power.
result = await session.call_tool("get_max_power", {"random_string": "dummy"})
Get margin ratio for a security.
result = await session.call_tool("get_margin_ratio", {"symbol": "HK.00700"})
Get market state.
result = await session.call_tool("get_market_state", {"market": "HK"})
Available markets: "HK", "US", "SH", "SZ"
Get security information.
result = await session.call_tool("get_security_info", { "market": "HK", "code": "00700" })
Get security list for a market.
result = await session.call_tool("get_security_list", {"market": "HK"})
Get filtered stock list based on conditions.
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 server time.
result = await session.call_tool("get_current_time", {"random_string": "dummy"})
Returns timestamp, formatted datetime, date, time and timezone.