by shuizhengqi1
Provides a standardized MCP interface to Futu OpenAPI, exposing real‑time market data, historical K‑lines, subscription streams, account queries, and trading operations for AI models.
A server that wraps the Futu OpenAPI with the Model Context Protocol (MCP) 2.0, enabling AI agents and applications to retrieve and interact with Hong Kong, US, and China stock market data through a uniform tool‑based API.
pipx install futu-stock-mcp-server (or from source)..env file with FUTU_HOST and FUTU_PORT pointing to a running Futu OpenD gateway and optional LOG_LEVEL.futu-mcp-server or python -m futu_stock_mcp_server.server.Q: Do I need a Futu OpenAPI account? A: Yes, a registered Futu account with OpenAPI permission and a running OpenD gateway are required.
Q: Can I run the server in Docker?
A: Yes, pull the Docker image and set the required FUTU_HOST and FUTU_PORT environment variables.
Q: How are credentials protected?
A: Credentials are never hard‑coded; they are read from a .env file that should be excluded from version control.
Q: What if the futu-mcp-server command is not found?
A: Ensure pipx installed the package and that its binary directory is on your PATH (e.g., ~/.local/bin).
Q: Which markets are supported? A: HK (Mainboard, GEM, H‑Share), US (NYSE, NASDAQ, AMEX), Shanghai, Shenzhen, and related derivatives.
Q: How do I subscribe to live data?
A: Use the subscribe tool with a list of symbols and subscription types such as QUOTE, TICKER, or K_1M.
Q: Can I use this server with non‑Python clients? A: Yes, any MCP‑compatible client (including Node.js SDKs) can connect using the standard stdio or WebSocket transport.
基于模型上下文协议(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
启用详细日志:
export LOG_LEVEL=DEBUG
futu-mcp-server
日志文件位置:./logs/futu_server.log
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.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by stripe
Integrates Stripe's APIs into LLM‑driven agent workflows via Python and TypeScript libraries, exposing tool definitions compatible with Model Context Protocol for seamless function calling.
by goat-sdk
Enables AI agents to send and receive payments, purchase goods and services, execute investment strategies, tokenize assets, and obtain financial insights by leveraging blockchains, stablecoins, and wallets.
by financial-datasets
Provides access to income statements, balance sheets, cash flow statements, stock prices, market news, and cryptocurrency data through MCP tools for AI assistants.
by alpacahq
Enables large language models to trade stocks and options, retrieve real‑time and historical market data, and manage portfolios using plain English commands through a local or remote MCP server.
by XeroAPI
Provides a bridge between the Model Context Protocol and Xero's API, enabling standardized access to Xero accounting and business features.
by stefanoamorelli
Provides an MCP server that connects AI models to SEC EDGAR filings, enabling real‑time retrieval of company filings, financial statements, and insider‑trading data with exact XBRL precision and verifiable filing references.
by ariadng
Enables AI LLMs to execute trades on the MetaTrader 5 platform through the Model Context Protocol.
by calvernaz
Provides access to Alpha Vantage stock market data via an MCP server, supporting stdio and HTTP streaming modes with optional OAuth 2.1 authentication.
by kukapay
Integrates the Freqtrade cryptocurrency trading bot with MCP, exposing its REST API as tools for AI agents to perform automated trading operations.