qmt-trade-mcp

基于 FastMCP 框架构建的 MCP（Model Context Protocol）服务，封装迅投 xtquant 行情数据接口和交易接口，通过 SSE 传输协议提供行情查询和交易能力。

免责声明：AI 可能会犯错，用户需自行承担交易带来的损失。本服务仅提供接口封装，不对交易结果负责。

联系方式（微信）： gold98986868、Az184114

环境要求

• Python >= 3.12
• uv 包管理器
• 已安装并配置 QMT/xtquant 运行环境（需自行安装迅投 QMT 终端，并保持 QMT 客户端登录运行）

快速开始

克隆项目

git clone https://github.com/novaair026-dev/qmt-trade-mcp.git
cd qmt-trade-mcp

安装依赖

uv sync

启动服务

uv run python main.py

服务默认监听 127.0.0.1:8000，可通过环境变量自定义：

MCP_HOST=0.0.0.0 MCP_PORT=9000 uv run python main.py

验证服务

访问 http://127.0.0.1:8000/sse 建立 SSE 连接后，即可通过 MCP 协议调用各工具。

项目结构

qmt-trade-mcp/
├── main.py                     # 服务入口，uvicorn 加载合并后的 MCP 应用
├── pyproject.toml              # 项目配置及依赖
├── src/
│   ├── xtdata_mcp/             # 行情数据模块
│   │   ├── __init__.py
│   │   ├── __main__.py
│   │   └── server.py            # 21 个行情数据 tools
│   └── xttrade_mcp/            # 交易模块
│       ├── __init__.py
│       ├── __main__.py
│       └── server.py            # 37 个交易 tools
└── tests/
    ├── __init__.py
    ├── conftest.py            # pytest fixtures（HTTP/SSE 传输测试客户端）
    ├── test_server.py         # 行情 tool 功能测试
    └── test_trader.py         # 交易 tool 功能测试

提供的 MCP Tools（共 58 个）

所有工具均支持通过 MCP 客户端调用，返回统一 JSON 格式。

行情数据

历史数据下载

除权除息

交易日历

合约与板块

财务数据

可转债

新股 / ETF

---

交易模块 MCP Tools（37 个）

注意：交易工具需要先调用 init_trader 初始化连接，并保持 QMT 客户端登录运行。

系统设置

下单 / 撤单

查询 - 股票账户

查询 - 信用账户

查询 - 其他

券源借券

响应格式

所有 tool 均返回统一 JSON 格式：

// 成功
{ "ok": true, "data":  }

// 失败（如 xtquant 未配置）
{ "ok": false, "error": "" }

测试

# 运行行情 tool 功能测试（需先启动 MCP 服务）
uv run pytest tests/test_server.py -v

# 运行交易 tool 功能测试（需先启动 MCP 服务）
uv run pytest tests/test_trader.py -v

# 运行所有测试
uv run pytest tests/ -v

测试使用 FastMCP Client HTTP/SSE 传输连接运行中的 MCP 服务（http://127.0.0.1:8000/sse），每个测试调用真实 xtquant 接口验证功能正常。

部署说明

本服务通过 SSE（Server-Sent Events）传输协议提供 MCP 接口，适用于兼容 SSE 的 MCP 客户端（如 Claude Desktop、Dify 等）。

推荐通过反向代理（如 Nginx）将服务暴露到指定路径或域名：

location /mcp {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
}

SSE 端点：GET /sse（建立 SSE 连接） 消息端点：POST /messages/?session_id=（调用工具）

Claude Code 配置

本服务以 SSE 传输模式运行，Claude Code 可通过 HTTP URL 方式接入。

方式一：命令行添加（推荐）

先在后台启动服务，再将 SSE URL 注册到 Claude Code：

# 1. 启动服务（后台运行）
uv run python main.py &
sleep 3

# 2. 添加到 Claude Code（全局）
claude mcp add xtdata-mcp --url http://127.0.0.1:8000/sse

# 3. 验证是否添加成功
claude mcp list

方式二：手动编辑配置文件

在 ~/.claude.json（全局）或项目根目录 .mcp.json（项目级）中添加：

{
  "mcpServers": {
    "xtquant-mcp": {
      "url": "http://127.0.0.1:8000/sse",
      "description": "迅投 xtquant 行情数据 + 交易接口"
    }
  }
}

方式三：直接启动 MCP 服务器

如果 Claude Code 支持 stdio 模式，也可以用 uvicorn 作为载体：

# 启动合并后的服务（行情+交易）
uvicorn main:app --host 127.0.0.1 --port 8000 --log-level warning

验证

添加成功后，在 Claude Code 中确认连接正常：

claude mcp list
# 应该看到 xtdata-mcp 显示 Connected

之后即可在对话中直接调用工具，例如：

帮我查询 600000.SH 的最新日线行情
获取银行板块的所有成分股
查看上证指数的最新成分股权重

帮我初始化交易通道
查询我的账户资产
买入 600000.SH 100股，价格 10.0元

注意事项

• 使用交易功能前需确保 QMT 客户端已登录运行，且登录时需勾选"独立交易"选项，否则交易工具返回 ok: false
• 首次使用需先调用 download_* 系列工具下载本地数据
• 部分工具（如 download_history_data2、download_index_weight）数据量较大，调用时可能耗时较长
• 交易为高风险操作，下单前请确认账户、股票代码、价格、数量等参数正确无误
• 市价单仅在实盘交易有效，模拟交易不支持市价单