TdxQuant MCP Server

An MCP (Model Context Protocol) wrapper based on the local tqcenter.py (TdxQuant strategy interface). AI clients (such as Cursor) can call tools via stdio or HTTP/SSE to retrieve market data, financial reports, sector information, formulas, and more.

Python package name: tdxquant-mcp (see pyproject.toml).

MCP Configuration: docs/mcp-configuration.md Agent Usage (call sequence, intent mapping, trading safety): docs/agent-usage.md TdxQuant Platform Introduction (official help summary + MCP tool description): docs/tdxquant-intro.md Agent Skill Package (Claude Code / OpenClaw / Hermes + SSE configuration): docs/agent-skills.md · skills/tdxquant-mcp/

Agent Skill Package

For Claude Code, OpenClaw, Hermes Agent, etc.: You can copy the directory skills/tdxquant-mcp/ (containing SKILL.md / skill.md and SSE configuration snippets/streamlined workflows under references/). Once tdx_mcp.main_http is started, the client connects to http://<MCP_HOST>:<MCP_PORT>/sse. See docs/agent-skills.md for installation and host path instructions.

Related MCP server: xcsc-tushare-mcp

Feature Overview

Tools are categorized into 9 groups (consistent with tools_catalog / tool_metadata):

Recommendation: First call the tool tools_catalog (no parameters) to return the list of categories and tools, then call specific tools as needed. Stock Code Format: For Shanghai/Shenzhen, generally 600519.SH, 000001.SZ (uppercase market suffix).

Repository Structure (Relevant to this project)

user/
├── tqcenter.py              # TdxQuant Python 接口（依赖 TPythClient.dll 等）
├── tdxdata_test.py          # 直连 tq 的脚本示例（非 MCP）
├── skills/tdxquant-mcp/     # Agent Skill（SSE工作流 + 各宿主 MCP 片段）
├── tdx_mcp/                 # MCP 可安装包
│   ├── main_stdio.py        # stdio 入口（Cursor本地 MCP 推荐）
│   ├── main_http.py         # HTTP/SSE入口
│   ├── config.py            # 环境变量：TQ_PATH 等
│   ├── service/tdx_service.py
│   └── server/              # 各工具注册模块
├── tests/                   # pytest（含可选集成测试）
├── pyproject.toml
├── .env.example
├── docs/
│   ├── mcp-configuration.md # MCP 配置（Cursor / Claude / SSE）
│   ├── agent-usage.md       # Agent 使用说明（工作流、意图对照、交易）
│   ├── agent-skills.md      # Skill 包安装（Claude Code / OpenClaw / Hermes）
│   ├── tdxquant-intro.md    # TdxQuant 简介索引（正文见包内 resources）
│   └── mirror-tdx-quant-help/  # 运行 sync脚本后：官方帮助镜像 Markdown（可选）
└── .cursor/mcp.json         # Cursor 项目级 MCP 示例（可选）

Prerequisites

1. The TdxQuant / TongDaXin terminal (with strategy capabilities) must be running locally, and the strategy path must be configured according to official instructions.

2. tqcenter.py must be importable in the project directory (path consistent with TPythClient.dll, etc., see TdxQuant documentation).

3. TQ_PATH must be configured (pointing to the strategy script path, consistent with tq.initialize requirements).

4. It is recommended to use uv to manage dependencies and run commands.

Installation

uv sync

HTTP/SSE mode requires ASGI dependencies:

uv sync --extra http

Development and testing:

uv sync --extra dev

TdxQuant Online Help Mirror (crawled pages from help.tdx.com.cn/quant/docs/, generating local Markdown, optional):

uv sync --extra sync-docs
python scripts/sync_tdx_help_docs.py

Output directory defaults to docs/mirror-tdx-quant-help/ (containing pages/, _manifest.json, README.md). See the instructions within that directory for details; copyright of the content belongs to TongDaXin, please refer to the online version as the authoritative source.

Environment Variables

Copy .env.example to .env and modify:

When the MCP process starts, it loads get_settings(); missing TQ_PATH will cause an immediate error.

Configuring MCP in Cursor (stdio)

The project provides an example .cursor/mcp.json (uv + envFile). After opening the root directory of this repository in Cursor, enable tdxquant in Settings → MCP.

For more complete instructions (including Claude Desktop, env inline, HTTP/SSE, troubleshooting), see docs/mcp-configuration.md.

Startup Methods

stdio (Recommended: Cursor, Claude Desktop, etc.)

uv run python -m tdx_mcp.main_stdio

HTTP / SSE (Independent process, for clients supporting remote MCP)

uv run python -m tdx_mcp.main_http

The listening address and port are determined by MCP_HOST / MCP_PORT (see .env).

Tool Names and Call Examples

The following names are exactly consistent with @mcp.tool(name="...") in the code. In different clients, the JSON field might be tool / name / toolName; refer to the documentation of the client you are using.

Get Tool Catalog

{
  "tool": "tools_catalog",
  "arguments": {}
}

Market: Last 60 Daily K-lines

{
  "tool": "market_get_kline",
  "arguments": {
    "stock_list": ["600519.SH"],
    "period": "1d",
    "count": 60,
    "dividend_type": "none"
  }
}

Stock Info: Extended Info

{
  "tool": "stock_get_more_info",
  "arguments": {
    "stock_code": "600519.SH"
  }
}

Sector: Constituent Stocks

{
  "tool": "sector_stocks",
  "arguments": {
    "block_code": "BK0475",
    "block_type": 0,
    "list_type": 0
  }
}

Financial: By Report Period

{
  "tool": "financial_get_report_by_date",
  "arguments": {
    "stock_list": ["600519.SH"],
    "year": 2024,
    "mmdd": 1231
  }
}

Trading: Order Preview (dry-run, default)

To place an actual order, set dry_run to false and assume the risks yourself; account_id is generally obtained via trade_get_account_id.

{
  "tool": "trade_order_stock",
  "arguments": {
    "account_id": 1001,
    "stock_code": "600519.SH",
    "order_type": 0,
    "order_volume": 100,
    "price_type": 0,
    "price": 1500.0,
    "dry_run": true
  }
}

Tools: Execute TdxQuant Formula

The main entry point is utility_formula_run; there is also an alias formula_run with the same behavior.

{
  "tool": "utility_formula_run",
  "arguments": {
    "formula_name": "KDJ",
    "formula_arg": "9,3,3",
    "mode": "zb"
  }
}

Testing

Unit Testing (No client connection)

uv run pytest tests/ -q

When integration environment variables are not set, integration test cases will be skipped, and only unit tests for parameters, directories, etc., will run.

Integration Testing (Requires TdxQuant login)

CMD:

set TDX_INTEGRATION=1
set TDX_STRICT_DATA=1
uv run pytest tests/test_tools_integration_tdxdata.py -m integration

PowerShell:

$env:TDX_INTEGRATION = "1"
$env:TDX_STRICT_DATA = "1"
uv run pytest tests/test_tools_integration_tdxdata.py -m integration

• TDX_STRICT_DATA: Optional, fails on empty data (default allows empty dict to facilitate connection troubleshooting).

• TDX_TRADE_ACCOUNT: Optional, account string for trading integration tests.

Script Example (Non-MCP)

tdxdata_test.py demonstrates direct calls to tqcenter.tq, used to verify interface behavior; it is independent of the MCP process.

Troubleshooting

License and Upstream

Behavior and data formats are subject to TdxQuant / TongDaXin and tqcenter.py; this repository is only for MCP wrapping and documentation organization.