TDX Finance MCP Plugin v3

<p align="center"> <strong>通达信金融数据服务 MCP 插件（精简版）</strong><br> <em>TDX (TongDaXin) Finance Data Service · Model Context Protocol Plugin</em> </p>

<p align="center"> <a href="#简介">简介</a> · <a href="#架构总览">架构总览</a> · <a href="#工具列表">工具列表</a> · <a href="#快速开始">快速开始</a> · <a href="#工具文档">工具文档</a> · <a href="#故障排查">故障排查</a> </p>

---

简介

TDX Finance MCP Plugin v3 是一个为 OpenClaw 平台设计的金融数据服务插件，提供通达信（TDX）A 股金融数据接口的统一访问能力。

本插件封装了 6 个经过验证的核心工具，并内置 45 个专业投资分析技能，覆盖 A 股实时行情、K线、F10 基本面、智能选股、指标筛选与代码检索等需求。

v3 与旧版的区别

v3 是在 v2 基础上的清理与精简版本，主要变更（详见 CHANGELOG.md）：

• 移除了 4 个依赖问达（Wenda）平台、长期返回 401 need login 的失效工具（wenda_news_query / wenda_report_query / wenda_notice_query / wenda_macro_query）。这些功能已在技能层迁移至 F10 模块，旧工具不再需要。
• 清除了此前散落在多个脚本与文档中的硬编码 API Token 与认证密钥。
• 删除了仓库内的调试 / 抓取 Cookie / 重复扫描脚本，只保留可发布的插件资产。
• 统一了版本号、仓库地址与技能数量等元数据。

现在工具层、清单（openclaw.plugin.json）与文档三者完全一致：6 个工具，全部可用。

一包包含：工具 + 技能

tdx-finance-mcp-plugin-v3/
├── index.js                 # 6 个数据工具（核心实现，单文件 ESM）
├── openclaw.plugin.json     # 插件清单（工具 + 技能声明）
├── skills/                  # 45 个专业投资技能（提示词 + agents 配置）
├── install.sh               # Linux/Mac 安装脚本
├── install.ps1              # Windows 安装脚本
├── config.example.json      # 配置示例
├── SKILLS.md                # 技能清单与触发词
├── CHANGELOG.md             # 版本变更记录
└── README.md                # 本文件

---

架构总览

本插件的 6 个工具调用 2 个不同的 API 服务器。理解这一架构是正确使用和调试的关键。

#	服务器地址	用途	涉及工具
1	http://tdxhub.icfqs.com:7615/TQLEX	F10 基本面、实时行情、K线、选股、指标	tdx_api_data, tdx_quotes, tdx_kline, tdx_screener, tdx_indicator_select
2	https://ai.icfqs.com:8965/v1/rag-entity-retrieve	RAG 实体代码/名称检索	tdx_lookup_stock

⚠️ 重要：不同工具使用不同的 Entry 名称和请求体格式（见 工具文档）。不要根据工具名猜测 Entry 名称。

---

工具列表

🟢 = 完全可用（基础 Token） | 🟡 = 部分 F10 模块需开通更高权限

#	工具名称	功能描述	服务器	Entry	状态
1	tdx_api_data	统一 F10 内部 API 调用（含盈利预测、热点题材、事件驱动等子模块）	服务器1	TdxSharePCCW.*	🟢 / 🟡
2	tdx_quotes	实时行情查询（报价、五档盘口、涨跌幅等）	服务器1	TdxShare.PBHQInfo	🟢
3	tdx_kline	K线历史数据查询（多周期、含复权）	服务器1	TdxShare.PBFXT	🟢
4	tdx_lookup_stock	股票/指数/基金代码 RAG 检索	服务器2	AI RAG	🟢
5	tdx_screener	自然语言智能选股	服务器1	JNLPSE:wendaQuery	🟢
6	tdx_indicator_select	金融指标选择与查询	服务器1	NLPSE:InfoSelectV2	🟢

实测结果（2026-06-20，标的 000001）

通过 test/run-tests.mjs 驱动真实插件代码实测。完整报告见 test/test-report.md。

• 6 个核心工具：全部可用 ✅（行情 ~134ms、K线 ~79ms、代码检索 ~233ms、选股 ~225ms、指标 ~1140ms、F10 ~84ms）。

• F10 子模块：大部分可用。 已验证可用的包括：公司概况 gsgk、公司概要 zxts/gsgy、盈利预测/预告 ybpj/yzyq·yjyg、事件与题材 rdtc/sjcd·zttzbkz、龙虎榜涨停/大宗/资金流 jyds/ztfx·dzjy·zjlx、机构与流通股东 gdyj/cgbd·jgcg·ltgd、股本结构 gbjg、主力持仓 zlcc、综合 comreq 等。

• 需更高权限的子模块（基础 Token 下不可用）：

  • 401 需登录：股东人数 gdyj/gdrs、分红历史 fhrz/fhlszs_gxl、融资融券 jyds/rzrq
  • E|-7202 未注册：fhrz_fh/fh、异动 iyds/yxsbxx

  如需这些数据，请联系通达信升级 Token 权限。依赖它们的 6 个技能（分红融资、龙虎榜、股东研究、交易信息、龙虎榜席位风格、涨停龙头）会在主数据可用的前提下自动降级（跳过受限子表）。

---

快速开始

前置要求

• Node.js ≥ 22.16.0（使用内置 fetch，运行时零额外依赖）
• OpenClaw：已安装并运行
• TDX API Token：从通达信官方获取的数据服务授权令牌

三步启动

1. 安装插件

git clone https://github.com/adambbhe/TDX-finance-mcp-plugin-v3.git
cd TDX-finance-mcp-plugin-v3

# 一键安装（自动配置 Token + 安装 45 个技能）
# Linux/Mac:
chmod +x install.sh && ./install.sh

# Windows:
.\install.ps1 -Token "你的TDX_API_TOKEN"

2. 配置 API Token

复制 config.example.json 为 config.json 并填入你的 Token（config.json 已被 .gitignore 忽略，不会误提交）：

{
  "plugins": {
    "tdx-finance-mcp": {
      "enabled": true,
      "config": { "tdxApiToken": "你的通达信API_TOKEN" }
    }
  }
}

或使用环境变量：

# Linux/Mac
export TDX_API_KEY="你的API_KEY"
# Windows PowerShell
$env:TDX_API_KEY = "你的API_KEY"

3. 启动 OpenClaw

openclaw start

插件会自动加载 6 个工具 + 45 个技能。

---

配置说明

tdxApiToken（必填）

通达信 API 授权令牌。插件将其作为 HTTP header token: <tdx-api-token> 发送。

Token 注入优先级：

1. 插件配置中的 tdxApiToken 字段
2. 环境变量 TDX_API_KEY（回退方案）

apiEndpoint（可选）

仅对服务器1的工具生效。默认 http://tdxhub.icfqs.com:7615/TQLEX。

优先级：参数 apiEndpoint → 配置 apiEndpoint → TDX_API_DATA_ENDPOINT → TDX_API_ENDPOINT → 硬编码默认值。

环境变量汇总

环境变量名	说明	影响范围
TDX_API_KEY	API Token（回退方案）	全部工具
TDX_API_DATA_ENDPOINT	自定义服务器1端点	服务器1工具

---

工具文档

⚠️ 每个工具的 Entry 名称、请求体格式和目标服务器都不同。以下信息均从源码 index.js 提取验证。

1. tdx_api_data — F10 基本面数据统一接口

• 服务器：http://tdxhub.icfqs.com:7615/TQLEX
• Entry 格式：动态，以 TdxSharePCCW. 等为前缀
• 请求体：{ Params: [...] }

// 盈利预测
{ "entry": "TdxSharePCCW.tdxf10_gg_ybpj", "code": "000001", "fixedTag": "yzyq" }
// 热点题材板块族谱
{ "entry": "TdxSharePCCW.tdxf10_gg_rdtc", "code": "000001", "fixedTag": "zttzbkz" }
// 事件驱动催化
{ "entry": "TdxSharePCCW.tdxf10_gg_rdtc", "code": "000001", "fixedTag": "sjcd" }

工具支持多种参数模板（raw / code-only / code-fixed-tag / fixed-tag-code-extra / code-date-range-page 等），可按 entry + fixedTag 自动推导。详见源码与各技能的 SKILL.md。

2. tdx_quotes — 实时行情查询

• Entry：TdxShare.PBHQInfo · 请求体：结构化对象

tdx_quotes code="000001" setcode="0"            # 平安银行（深市）
tdx_quotes code="600519" setcode="1" hasProInfo="1"  # 贵州茅台（沪市）

setcode：0=深市，1=沪市，2=北交所。

3. tdx_kline — K线历史数据

• Entry：TdxShare.PBFXT · 请求体：结构化对象

tdx_kline code="000001" setcode="0" period="4" wantNum="30"   # 日K 最近30根
tdx_kline code="600519" setcode="1" period="6" wantNum="12"   # 月K

period：4=日K，5=周K，6=月K，3=60分钟，9=1分钟（完整对照见源码）。

4. tdx_lookup_stock — 代码/名称检索

• 服务器：https://ai.icfqs.com:8965/v1/rag-entity-retrieve（独立于主 API）
• 请求体：{ query, range }

tdx_lookup_stock query="平安银行"
tdx_lookup_stock query="腾讯" range="HK-GP"

range：AG=A股（默认），HK-GP=港股，JJ=基金，MG-GP=美股，ZS=指数 等。

5. tdx_screener — 自然语言智能选股

• Entry：JNLPSE:wendaQuery · 请求体：[{ message, rang, pageNo, pageSize }]

tdx_screener message="涨停"
tdx_screener message="主板 小盘 低价 涨停"

6. tdx_indicator_select — 指标选择与查询

• Entry：NLPSE:InfoSelectV2 · 请求体：{ message, rang }

tdx_indicator_select message="000001 技术指标"
tdx_indicator_select message="银行业估值对比"

---

认证机制

所有请求统一在 Header 中携带 Token：

Content-Type: application/json
token: {your_tdx_api_token}

Token 来源优先级：插件配置 tdxApiToken → 环境变量 TDX_API_KEY。

🔒 安全提示：不要把真实 Token 写入源码或提交到仓库。请使用 config.json（已忽略）或环境变量。

---

故障排查

Q：如何获取 TDX API Token？ 联系通达信官方申请数据服务权限。Token 通常为 TDX-xxxx... 格式。

Q：接口返回 503 / S14042 错误？ 通常是 Token 权限不足、服务端维护或网络问题。确认能访问 tdxhub.icfqs.com:7615 与 ai.icfqs.com:8965。

Q：tdx_api_data 能用但 tdx_quotes/tdx_kline 报错？ 正常现象——三者使用完全不同的 Entry（TdxSharePCCW.* vs TdxShare.PBHQInfo vs TdxShare.PBFXT）。请勿根据工具名猜测 Entry。

Q：部分 F10 数据返回 E|-7201 / E|-7202？ 该模块未在当前 Token 下注册，需联系通达信升级权限。

Q：PowerShell 测试失败但 Node.js 成功？ 已知差异。请在 Node.js ≥ 22 环境运行，调试时使用原生 fetch。

---

已知注意事项

1. Entry 名称 ≠ 工具名：永远从源码读取，不要猜测。
2. 两种不同的请求体格式：tdx_api_data 用 { Params: [...] }；tdx_quotes/tdx_kline 用结构化对象；tdx_screener 用数组。
3. 两个不同的服务器：不要假设所有请求都发往同一地址。

---

许可证

本项目基于 MIT License 开源，详见 LICENSE。

---

<p align="center">Made with ❤️ by TDX Team · v3.0.0</p>