Content
# Tool List
<p align="center">
<strong>TDX Finance MCP Plugin v3</strong><br>
<em>TDX (TongDaXin) Finance Data Service · Model Context Protocol Plugin</em>
</p>
<p align="center">
<a href="#introduction">Introduction</a> ·
<a href="#architecture-overview">Architecture Overview</a> ·
<a href="#tool-list">Tool List</a> ·
<a href="#quick-start">Quick Start</a> ·
<a href="#tool-documentation">Tool Documentation</a> ·
<a href="#troubleshooting">Troubleshooting</a>
</p>
---
## Introduction
**TDX Finance MCP Plugin v3** is a financial data service plugin designed for the OpenClaw platform, providing a unified access capability to the TDX (TongDaXin) A-share financial data interface.
This plugin encapsulates **6 core tools** that have been verified and **45 professional investment analysis skills**, covering A-share real-time market quotes, K-line, F10 basic information, intelligent stock selection, indicator screening, and code retrieval.
### v3 vs. Previous Versions
v3 is a **cleanup and streamlined version** based on v2, with major changes (see [CHANGELOG.md](./CHANGELOG.md)):
- Removed 4 tools that were dependent on the Wenda platform and had long been returning `401 need login` errors (`wenda_news_query` / `wenda_report_query` / `wenda_notice_query` / `wenda_macro_query`). These functions have been migrated to the F10 module at the skill level, and the old tools are no longer needed.
- Cleared hard-coded API tokens and authentication keys that were scattered in multiple scripts and documents.
- Deleted debugging scripts, cookie grabbing scripts, and duplicate scanning scripts from the repository, leaving only releasable plugin assets.
- Unified version numbers, repository addresses, and skill counts.
> Now the tool layer, list (`openclaw.plugin.json`), and documentation are completely consistent: **6 tools, all available**.
### One Package Includes: Tools + Skills
```
tdx-finance-mcp-plugin-v3/
├── index.js # 6 data tools (core implementation, single file ESM)
├── openclaw.plugin.json # plugin list (tool + skill declaration)
├── skills/ # 45 professional investment skills (prompts + agents configuration)
├── install.sh # Linux/Mac installation script
├── install.ps1 # Windows installation script
├── config.example.json # configuration example
├── SKILLS.md # skill list and trigger words
├── CHANGELOG.md # version change record
└── README.md # this file
```
---
## Architecture Overview
The 6 tools of this plugin call **2 different API servers**. Understanding this architecture is crucial for correct usage and debugging.
| # | Server Address | Purpose | Involved Tools |
|---|-----------|------|---------|
| **1** | `http://tdxhub.icfqs.com:7615/TQLEX` | F10 basic information, real-time market quotes, K-line, stock selection, indicator | `tdx_api_data`, `tdx_quotes`, `tdx_kline`, `tdx_screener`, `tdx_indicator_select` |
| **2** | `https://ai.icfqs.com:8965/v1/rag-entity-retrieve` | RAG entity code/name retrieval | `tdx_lookup_stock` |
> ⚠️ **Important**: Different tools use different entry names and request body formats (see [Tool Documentation](#tool-documentation)). **Do not guess the entry name based on the tool name**.
---
## Tool List
> 🟢 = fully available (basic token) | 🟡 = some F10 modules require higher permissions
| # | Tool Name | Function Description | Server | Entry | Status |
|---|---------|---------|--------|-------|------|
| 1 | **tdx_api_data** | Unified F10 internal API call (including profit forecast, hot topics, event-driven, etc.) | Server 1 | `TdxSharePCCW.*` | 🟢 / 🟡 |
| 2 | **tdx_quotes** | Real-time market quote query (quotation, 5-level quote, price limit, etc.) | Server 1 | `TdxShare.PBHQInfo` | 🟢 |
| 3 | **tdx_kline** | K-line historical data query (multi-period, including adjustment) | Server 1 | `TdxShare.PBFXT` | 🟢 |
| 4 | **tdx_lookup_stock** | Stock/index/fund code RAG retrieval | Server 2 | AI RAG | 🟢 |
| 5 | **tdx_screener** | Natural language intelligent stock selection | Server 1 | `JNLPSE:wendaQuery` | 🟢 |
| 6 | **tdx_indicator_select** | Financial indicator selection and query | Server 1 | `NLPSE:InfoSelectV2` | 🟢 |
### Actual Test Results (2026-06-20, target 000001)
> Driven by `test/run-tests.mjs` to run real plugin code test. Complete report see [test/test-report.md](./test/test-report.md).
- **6 core tools: all available ✅** (market quotes ~134ms, K-line ~79ms, code retrieval ~233ms, stock selection ~225ms, indicators ~1140ms, F10 ~84ms).
- **F10 sub-modules: mostly available.** Verified available sub-modules include: company overview `gsgk`, company summary `zxts/gsgy`, profit forecast/pre-announcement `ybpj/yzyq·yjyg`, event and theme `rdtc/sjcd·zttzbkz`, dragon tiger list price limit/bulk transaction/fund flow `jyds/ztfx·dzjy·zjlx`, institutional and circulating shareholder `gdyj/cgbd·jgcg·ltgd`, share capital structure `gbjg`, main force position `zlcc`, comprehensive `comreq`, etc.
- **Sub-modules requiring higher permissions (not available with basic token):**
- `401 need login`: shareholder number `gdyj/gdrs`, dividend history `fhrz/fhlszs_gxl`, margin trading `jyds/rzrq`
- `E|-7202 not registered`: `fhrz_fh/fh`, abnormal `iyds/yxsbxx`
If you need these data, please contact TDX to upgrade token permissions. The 6 skills dependent on them will automatically downgrade (skip restricted sub-tables) if the main data is available.
---
## Quick Start
### Prerequisites
- **Node.js** ≥ 22.16.0 (using built-in fetch, zero additional dependencies at runtime)
- **OpenClaw**: installed and running
- **TDX API Token**: data service authorization token obtained from TDX
### Three Steps to Start
#### 1. Install Plugin
```bash
git clone https://github.com/adambbhe/TDX-finance-mcp-plugin-v3.git
cd TDX-finance-mcp-plugin-v3
# One-click installation (automatically configure token + install 45 skills)
# Linux/Mac:
chmod +x install.sh && ./install.sh
# Windows:
.\install.ps1 -Token "your TDX_API_TOKEN"
```
#### 2. Configure API Token
Copy `config.example.json` to `config.json` and fill in your token (`config.json` is ignored by `.gitignore`, will not be submitted by mistake):
```json
{
"plugins": {
"tdx-finance-mcp": {
"enabled": true,
"config": { "tdxApiToken": "your TDX_API_TOKEN" }
}
}
}
```
Or use environment variables:
```bash
# Linux/Mac
export TDX_API_KEY="your API_KEY"
# Windows PowerShell
$env:TDX_API_KEY = "your API_KEY"
```
#### 3. Start OpenClaw
```bash
openclaw start
```
The plugin will automatically load **6 tools + 45 skills**.
---
## Configuration Description
### `tdxApiToken` (required)
TDX API authorization token. The plugin sends it as an HTTP header `token: <tdx-api-token>`.
**Token injection priority**:
1. `tdxApiToken` field in plugin configuration
2. Environment variable `TDX_API_KEY` (fallback)
### `apiEndpoint` (optional)
Only effective for tools on **Server 1**. Default is `http://tdxhub.icfqs.com:7615/TQLEX`.
**Priority**: parameter `apiEndpoint` → configuration `apiEndpoint` → `TDX_API_DATA_ENDPOINT` → `TDX_API_ENDPOINT` → hard-coded default value.
### Environment Variables
| Environment Variable | Description | Affected Scope |
|-----------|------|---------|
| `TDX_API_KEY` | API token (fallback) | all tools |
| `TDX_API_DATA_ENDPOINT` | custom server 1 endpoint | tools on server 1 |
---
## Tool Documentation
> ⚠️ Each tool has different entry names, request body formats, and target servers. The following information is verified from the source code `index.js`.
### 1. `tdx_api_data` — Unified F10 Basic Information Interface
- **Server**: `http://tdxhub.icfqs.com:7615/TQLEX`
- **Entry format**: dynamic, prefixed with `TdxSharePCCW.`
- **Request body**: `{ Params: [...] }`
```json
// profit forecast
{ "entry": "TdxSharePCCW.tdxf10_gg_ybpj", "code": "000001", "fixedTag": "yzyq" }
// hot topic block
{ "entry": "TdxSharePCCW.tdxf10_gg_rdtc", "code": "000001", "fixedTag": "zttzbkz" }
// event-driven catalyst
{ "entry": "TdxSharePCCW.tdxf10_gg_rdtc", "code": "000001", "fixedTag": "sjcd" }
```
The tool supports multiple parameter templates (`raw` / `code-only` / `code-fixed-tag` / `fixed-tag-code-extra` / `code-date-range-page`, etc.), which can be automatically deduced by `entry + fixedTag`. See source code and skill `SKILL.md` for details.
### 2. `tdx_quotes` — Real-time Market Quote Query
- **Entry**: `TdxShare.PBHQInfo` · **Request body**: structured object
```bash
tdx_quotes code="000001" setcode="0" # Ping An Bank (Shenzhen)
tdx_quotes code="600519" setcode="1" hasProInfo="1" # Guizhou茅台 (Shanghai)
```
`setcode`: `0`=Shenzhen, `1`=Shanghai, `2`=Beijing.
### 3. `tdx_kline` — K-line Historical Data
- **Entry**: `TdxShare.PBFXT` · **Request body**: structured object
```bash
tdx_kline code="000001" setcode="0" period="4" wantNum="30" # daily K-line for recent 30 roots
tdx_kline code="600519" setcode="1" period="6" wantNum="12" # monthly K-line
```
`period`: `4`=daily K-line, `5`=weekly K-line, `6`=monthly K-line, `3`=60 minutes, `9`=1 minute (see complete mapping in source code).
### 4. `tdx_lookup_stock` — Code/Name Retrieval
- **Server**: `https://ai.icfqs.com:8965/v1/rag-entity-retrieve` (independent of main API)
- **Request body**: `{ query, range }`
```bash
tdx_lookup_stock query="Ping An Bank"
tdx_lookup_stock query="Tencent" range="HK-GP"
```
`range`: `AG`=A-share (default), `HK-GP`=Hong Kong stock, `JJ`=fund, `MG-GP`=US stock, `ZS`=index, etc.
### 5. `tdx_screener` — Natural Language Intelligent Stock Selection
- **Entry**: `JNLPSE:wendaQuery` · **Request body**: `[{ message, rang, pageNo, pageSize }]`
```bash
tdx_screener message="price limit"
tdx_screener message="main board small disk low price price limit"
```
### 6. `tdx_indicator_select` — Financial Indicator Selection and Query
- **Entry**: `NLPSE:InfoSelectV2` · **Request body**: `{ message, rang }`
```bash
tdx_indicator_select message="000001 technical indicators"
tdx_indicator_select message="bank industry valuation comparison"
```
---
## Authentication Mechanism
All requests uniformly carry tokens in the header:
```
Content-Type: application/json
token: {your_tdx_api_token}
```
Token source priority: plugin configuration `tdxApiToken` → environment variable `TDX_API_KEY`.
> 🔒 **Security tip**: do not write real tokens into source code or submit to repository. Use `config.json` (ignored) or environment variables.
---
## Troubleshooting
**Q: OpenClaw installation reports validation warning / tool not registered / initialization blocked?**
Fixed in **v3.1.2**. The root cause is **plugin id mismatch**: `id: "tdx-finance"` in `index.js` and `id: "tdx-finance-mcp"` in manifest `openclaw.plugin.json` are inconsistent, and OpenClaw will fail to verify and register tools (**unrelated to your configuration value, so changing configuration won't pass**). The fix is to align `id`/`name` in `index.js` to `tdx-finance-mcp` / `TDX Finance MCP`.
Upgrade to ≥3.1.2, `config.json` only needs to fill in token:
```json
{ "plugins": { "tdx-finance-mcp": { "enabled": true, "config": { "tdxApiToken": "TDX-your token" } } } }
```
Then reload the plugin. Custom endpoint modification uses environment variable `TDX_API_DATA_ENDPOINT` (v3.1.2 and above config no longer contains `apiEndpoint` field).
> Note: v3.1.2 also simplifies `configSchema` (removes `format:"uri"`, empty default + pattern, `additionalProperties:false`) as a secondary hardening, but that is **not** the root cause of this installation failure.
**Q: How to obtain TDX API Token?**
Contact TDX for data service permission. Token is usually in the format of `TDX-xxxx...`.
**Q: Interface returns 503 / S14042 error?**
Usually token permission is insufficient, server maintenance, or network issues. Confirm access to `tdxhub.icfqs.com:7615` and `ai.icfqs.com:8965`.
**Q: `tdx_api_data` works but `tdx_quotes`/`tdx_kline` reports error?**
Normal phenomenon - the three use completely different entries (`TdxSharePCCW.*` vs `TdxShare.PBHQInfo` vs `TdxShare.PBFXT`). Please do not guess entries based on tool names.
**Q: Some F10 data returns `E|-7201` / `E|-7202`?**
The module is not registered under the current token and requires TDX to upgrade permissions.
**Q: PowerShell test fails but Node.js succeeds?**
Known differences. Please run in Node.js ≥ 22 environment, and use native `fetch` for debugging.
---
## Known Notes
1. **Entry name ≠ tool name**: always read from source code, do not guess.
2. **Two different request body formats**: `tdx_api_data` uses `{ Params: [...] }`; `tdx_quotes`/`tdx_kline` use structured objects; `tdx_screener` uses array.
3. **Two different servers**: do not assume all requests are sent to the same address.
---
## License
This project is open-sourced under **MIT License**, see [LICENSE](./LICENSE).
---
<p align="center">Made with ❤️ by TDX Team · v3.0.0</p>
Connection Info
You Might Also Like
No recommendations available