QMT MCP Server

将迅投 miniQMT 的常用接口封装为 MCP (Model Context Protocol) 工具，让 AI 助手（如 Claude、Hermes 等）能够直接查询 A 股行情、查询账户、下达交易指令。

⚠️ 风险提示：本服务包含真实下单 / 撤单功能（place_order / cancel_order），调用前请务必确认参数，避免造成实际资金损失。

功能概览

本项目提供三类 MCP 工具：

另外提供一个资源 qmt://info，用于查看 QMT 连接路径、账号和连接状态。

交易口令 token

为防止 AI 未经确认执行真实交易，place_order / cancel_order 两个交易操作工具 必须传入交易口令 token，口令校验通过后才会执行下单 / 撤单，否则直接拒绝。

• 口令为机密信息，格式不在此文档公开（由服务端与授权使用者另行约定，每日更换）。 请勿将口令格式写入提示词、示例或任何可能被 AI 读取到的上下文。

• agent 无法从工具描述、错误提示中推导出口令格式；需要口令时应向使用者询问。

• 行情查询与账户查询工具不受口令保护，可直接调用。

Related MCP server: 国金QMT-MCP

前置依赖

1. miniQMT 客户端：必须已安装、启动并登录（行情和交易都依赖 miniQMT 进程）。

2. Python 3.10+

3. xtquant（miniQMT 自带，不在 PyPI）：将 miniQMT 安装目录下的 xtquant 加入 PYTHONPATH，或拷贝到项目的 site-packages。

💡 本项目自身零第三方依赖：MCP 协议层用 Python 标准库手写（见 mcp_server_core.py），无需 pip install mcp 或 pandas。 （xtquant 内部会 import pandas 作为传递依赖，但我们的代码不直接依赖它。）

设置 xtquant 路径（Windows 示例）：

set PYTHONPATH=D:\QMT\bin.x64\Lib\site-packages

配置

所有配置项通过环境变量覆盖，默认值见 config.py：

建议在启动前导出环境变量：

export QMT_ACCOUNT=你的资金账号
export QMT_PATH="D:/QMT/userdata_mini"
# HTTP 模式建议设置 API Token（留空则不启用认证）
export MCP_API_TOKEN="你的随机 token"

运行方式

1. stdio 模式（默认，供 MCP 客户端通过子进程调用）

python qmt-mcp-server.py

2. HTTP / SSE 模式（独立运行，远程访问）

python qmt-mcp-server.py --transport http --host 0.0.0.0 --port 8765

HTTP API Token 认证：当设置了 MCP_API_TOKEN 环境变量时，所有 POST 请求须携带 Authorization: Bearer <token> 头部；GET / 健康检查保持公开，但仅返回最少信息（不暴露工具数量）。未设置 token 时认证关闭，向后兼容。客户端调用示例：

curl -X POST http://host:8765/ \
  -H "Authorization: Bearer <你的 token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 MCP 客户端中接入

Claude Desktop / Hermes（stdio）

在客户端配置文件中加入：

{
  "mcpServers": {
    "qmt": {
      "command": "python",
      "args": ["D:/QMT-gjzq/workspace/mcp_server/qmt-mcp-server.py"],
      "env": {
        "QMT_ACCOUNT": "你的资金账号",
        "QMT_PATH": "D:/QMT/userdata_mini"
      }
    }
  }
}

HTTP / SSE 模式

服务以 --transport http 启动后，客户端通过 SSE URL 接入：

http://<host>:8765/sse

代码结构

mcp_server/
├── qmt-mcp-server.py   # MCP Server 入口，定义所有工具/资源（业务层）
├── mcp_server_core.py  # 轻量 MCP 协议层（纯标准库，stdio + HTTP）
├── qmt_client.py       # QMT 客户端封装（xtdata 行情 + xttrader 交易），单例
├── config.py           # 配置项（环境变量读取）
├── requirements.txt    # 依赖说明（项目自身零第三方依赖）
├── ord_attrs.txt       # 委托对象字段参考
├── pos_attrs.txt       # 持仓对象字段参考
├── trd_attrs.txt       # 成交对象字段参考
└── README.md

• qmt_client.QMTClient 采用懒初始化：行情接口直接走 xtdata，交易接口在首次调用时才连接 XtQuantTrader 并订阅账户。

• 全局通过 get_client() 获取单例，避免重复连接。

股票代码格式

统一使用 代码.市场 格式，例如：

• 上交所：600519.SH、000001.SH（上证指数）

• 深交所：000001.SZ、300750.SZ

使用示例

向 AI 提问示例：

• 「查一下贵州茅台和五粮液的最新行情」→ 调用 get_stock_quote

• 「下载 600519 最近 100 根日线」→ 调用 get_kline_data

• 「我的账户现在有多少可用资金？」→ 调用 get_account_asset

• 「以 1700 元买入 100 股 600519.SH」→ 调用 place_order（须传交易口令 token，向使用者索取）⚠️ 真实下单

常见问题

• 连接 miniQMT 失败 (code≠0)：确认 miniQMT 已启动并登录对应账号；QMT_PATH 是否指向正确的 userdata_mini 目录。

• 订阅账户失败：检查 QMT_ACCOUNT 是否与 miniQMT 登录账号一致。

• 行情数据为空：miniQMT 必须在交易/行情会话中，部分数据需要先订阅或下载。

• ModuleNotFoundError: xtquant：将 miniQMT 自带的 xtquant 目录加入 PYTHONPATH。

免责声明

本项目仅作技术交流与个人量化研究用途，不构成任何投资建议。使用本工具进行真实交易造成的任何盈亏，由使用者自行承担。