tdx-mcp

MCP 服务器（STDIO），将客户端的工具调用代理到已部署的 tdx-api HTTP 接口。适用于通过 MCP 在对话中查询行情、K 线、分时、任务等数据服务，适配 tdx-api 项目。

基础信息

• 后端地址示例：http://ip:端口
• 健康检查：/api/health
• 返回格式参考：tdx-api/API_接口文档.md（统一 {"code":0,"message":"success","data":...}）

前置部署

• 先部署股票数据查询服务：https://github.com/oficcejo/tdx-api
• 部署完成后获取服务地址（例如 http://ip:端口），在客户端配置中填入该地址。

版本更新 0.1.3

• 修复 MCP 返回内容类型兼容问题：所有工具统一返回 content[0].type="text"，避免触发客户端 invalid_union 校验错误。
• 工具描述增强：每个接口均补充 Args 与 Returns 说明，方便直接复制到提示词中使用。
• 新增本地验证脚本 test_desc.js，可快速检查工具列表与返回格式。

客户端配置示例（Claude Desktop）

{
  "mcpServers": {
    "tdx-mcp": {
      "command": "npx",
      "args": ["-y", "[email protected]", "--base", "http://ip:端口"]
    }
  }
}

安装与启动（STDIO）

• 准备
  • cd tdx-mcp
  • npm install
  • npm run build
• 使用 npx（发布后）
  • npx -y [email protected] --base http://ip:端口
• 本地运行（开发调试）
  • TDX_API_BASE=http://ip:端口 node dist/index.js

核心工具速查（可直接复制到提示词）

| 工具名 | 一句话用途 + 参数 + 返回 | |--------|--------------------------| | get_quote | 获取股票实时五档行情。Args: code: 股票代码（如 603686）。Returns: JSON 文本，含最新价、五档买卖、成交量、成交额等。 | | get_kline | 获取股票K线数据。Args: code: 股票代码；type: 周期（day/week/month/minute1/minute5...）。Returns: JSON 文本，含开高低收、成交量、时间戳列表。 | | get_minute | 获取股票当日分时数据（分钟线）。Args: code: 股票代码。Returns: JSON 文本，含 240 条分钟级价格、成交量、成交额。 | | get_trade | 获取股票当日逐笔成交明细。Args: code: 股票代码。Returns: JSON 文本，含成交时间、价格、成交量、买卖方向等明细列表。 | | search_stock | 搜索股票代码/名称。Args: keyword: 股票代码或名称关键词。Returns: JSON 文本，含匹配股票的代码、交易所、名称列表。 | | get_stock_info | 获取股票综合信息（行情+K线+分时）。Args: code: 股票代码。Returns: JSON 文本，一次性返回 quote、kline、minute 三个接口的合并数据。 |

更多工具（指数、ETF、任务、交易日等）详见 USAGE.md。

使用示例（提示词直接可用）

请用 get_quote 查 603686 的实时行情，并用 get_kline 拿最近 30 条日K，把收盘价和成交量用 Markdown 表格输出。

注意事项

• 价格单位：厘（元=返回值/1000）
• 成交量单位：手（股=返回值×100）
• 日/周/月 K 线默认前复权；分钟与小时为原始数据
• 若遇到大段数据，建议在 MCP 客户端开启分页或使用 limit 参数

版本更新记录

0.1.3

• 所有工具中文描述补全，含 Args/Returns 说明，可直接复制到提示词
• 内容类型统一为 text，彻底消除 invalid_union 校验错误

0.1.2

• 修复 MCP 返回内容类型兼容问题（统一 content[0].type="text"）
• 新增本地验证脚本 test_desc.js

0.1.1

• 初始发布，支持股票/指数/ETF/任务等 30+ 接口代理