TdxQuant MCP-Server

Eine MCP (Model Context Protocol)-Kapselung basierend auf dem lokalen tqcenter.py (TdxQuant / TongDaXin Strategie-Schnittstelle). KI-Clients (wie Cursor) können Tools über stdio oder HTTP/SSE aufrufen, um Kursdaten, Finanzdaten, Sektordaten, Formeln usw. abzurufen.

Python-Paketname: tdxquant-mcp (siehe pyproject.toml).

MCP-Anbindung: docs/mcp-configuration.md Agent-Nutzung (Aufrufreihenfolge, Intent-Abgleich, Handelssicherheit): docs/agent-usage.md Einführung in die TdxQuant-Plattform (Offizielle Hilfe + MCP-Tool-Erklärung): docs/tdxquant-intro.md Agent Skill-Paket (Claude Code / OpenClaw / Hermes + SSE-Konfiguration): docs/agent-skills.md · skills/tdxquant-mcp/

Agent Skill-Paket

Für Claude Code, OpenClaw, Hermes Agent usw.: Das Verzeichnis skills/tdxquant-mcp/ kann kopiert werden (enthält SKILL.md / skill.md sowie SSE-Konfigurationsfragmente und optimierte Workflows unter references/). In Verbindung mit dem gestarteten tdx_mcp.main_http verbinden sich Clients mit http://<MCP_HOST>:<MCP_PORT>/sse. Installations- und Host-Pfad-Anweisungen finden Sie unter docs/agent-skills.md.

Funktionsübersicht

Die Tools sind in 9 Kategorien unterteilt (entsprechend tools_catalog / tool_metadata):

Empfehlung: Rufen Sie zuerst das Tool tools_catalog (ohne Parameter) auf, um die Kategorien und die Tool-Liste zu erhalten, und rufen Sie dann die spezifischen Tools nach Bedarf auf. Format der Wertpapiercodes: Für Shanghai/Shenzhen etc. in der Regel 600519.SH, 000001.SZ (Marktsuffix in Großbuchstaben).

Repository-Struktur (relevant für dieses Projekt)

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 示例（可选）

Voraussetzungen für den Betrieb

1. Das TdxQuant / TongDaXin Terminal (einschließlich Strategiefunktionen) muss lokal ordnungsgemäß ausgeführt werden können und die Strategiepfade müssen gemäß der offiziellen Anleitung konfiguriert sein.

2. Im Projektverzeichnis muss tqcenter.py importierbar sein (der Pfad muss mit TPythClient.dll usw. übereinstimmen, siehe TdxQuant-Dokumentation).

3. TQ_PATH muss konfiguriert sein (zeigt auf den Pfad der Strategieskripte, wie von tq.initialize gefordert).

4. Es wird empfohlen, uv zur Verwaltung von Abhängigkeiten und Ausführungsbefehlen zu verwenden.

Installation

uv sync

Für den HTTP/SSE-Modus sind ASGI-Abhängigkeiten erforderlich:

uv sync --extra http

Entwicklung und Tests:

uv sync --extra dev

TongDaXin Quant Online-Hilfe-Spiegel (Crawling der Seiten unter help.tdx.com.cn/quant/docs/, Erstellung von lokalem Markdown, optional):

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

Das Ausgabeverzeichnis ist standardmäßig docs/mirror-tdx-quant-help/ (enthält pages/, _manifest.json, README.md). Details finden Sie in den Anweisungen in diesem Verzeichnis; das Urheberrecht am Text liegt bei TongDaXin, bitte beziehen Sie sich auf die Online-Version.

Umgebungsvariablen

Kopieren Sie .env.example nach .env und passen Sie es an:

Beim Start des MCP-Prozesses wird get_settings() geladen. Das Fehlen von TQ_PATH führt zu einem direkten Fehler.

MCP in Cursor konfigurieren (stdio)

Im Projekt ist ein Beispiel .cursor/mcp.json enthalten (uv + envFile). Nachdem Sie das Stammverzeichnis dieses Repositorys in Cursor geöffnet haben, aktivieren Sie tdxquant unter Einstellungen → MCP.

Eine vollständigere Anleitung (einschließlich Claude Desktop, env-Inline, HTTP/SSE, Fehlerbehebung) finden Sie unter docs/mcp-configuration.md.

Startmethoden

stdio (Empfohlen: Cursor, Claude Desktop etc.)

uv run python -m tdx_mcp.main_stdio

HTTP / SSE (Unabhängiger Prozess, für Clients, die Remote-MCP unterstützen)

uv run python -m tdx_mcp.main_http

Die Listen-Adresse und der Port werden durch MCP_HOST / MCP_PORT bestimmt (siehe .env).

Tool-Namen und Aufrufbeispiele

Die folgenden Namen stimmen exakt mit @mcp.tool(name="...") im Code überein. In verschiedenen Clients können die JSON-Felder tool / name / toolName lauten, bitte richten Sie sich nach der Dokumentation Ihres verwendeten Clients.

Tool-Verzeichnis abrufen

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

Marktdaten: Letzte 60 Tageslinien

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

Aktieninformationen: Erweiterte Informationen

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

Sektoren: Bestandswerte

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

Finanzen: Nach Berichtszeitraum

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

Handel: Auftrags-Vorschau (dry-run, Standard)

Für den tatsächlichen Auftrag muss dry_run auf false gesetzt werden, und Sie tragen das Risiko selbst; account_id wird normalerweise über trade_get_account_id abgerufen.

{
  "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: TongDaXin-Formel ausführen

Der Haupteinstiegspunkt ist utility_formula_run; es gibt auch den Alias formula_run, das Verhalten ist identisch.

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

Tests

Unit-Tests (ohne Client-Verbindung)

uv run pytest tests/ -q

Wenn keine Umgebungsvariablen für die Integration gesetzt sind, werden Integrations-Testfälle übersprungen und nur Unit-Tests für Parameter, Verzeichnisse usw. ausgeführt.

Integrationstests (TongDaXin muss angemeldet sein)

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, schlägt bei leeren Daten fehl (Standard erlaubt leere dicts zur einfacheren Fehlerbehebung der Verbindung).

• TDX_TRADE_ACCOUNT: Optional, Account-String für Handels-Integrationstests.

Skriptbeispiel (kein MCP)

tdxdata_test.py demonstriert den direkten Aufruf von tqcenter.tq, um das Schnittstellenverhalten zu vergleichen; es ist unabhängig vom MCP-Prozess.

Fehlerbehebung

Lizenz und Upstream

Verhalten und Datenformate basieren auf TdxQuant / TongDaXin und tqcenter.py; dieses Repository dient lediglich der MCP-Kapselung und Dokumentationsaufbereitung.