TdxQuant MCP サービス

ローカルの tqcenter.py（TdxQuant / 通達信戦略インターフェース）に基づいた MCP（Model Context Protocol） ラッパーです。AIクライアント（Cursorなど）は、stdioまたはHTTP/SSEを通じてツールを呼び出し、相場、財務、セクター、数式などのデータを取得できます。

Pythonパッケージ名：tdxquant-mcp（pyproject.tomlを参照）。

MCP接続： docs/mcp-configuration.md Agentの使用（呼び出し順序、意図の照合、取引の安全性）： docs/agent-usage.md TdxQuantプラットフォームの概要（公式ヘルプの整理 + MCPツール説明）： docs/tdxquant-intro.md Agent Skillパッケージ（Claude Code / OpenClaw / Hermes + SSE設定）： docs/agent-skills.md · skills/tdxquant-mcp/

Agent Skillパッケージ

Claude Code、OpenClaw、Hermes Agentなど向け：ディレクトリ skills/tdxquant-mcp/ をコピーして使用できます（SKILL.md / skill.md および references/ 下のSSE設定スニペット、簡略化されたワークフローが含まれています）。起動済みの tdx_mcp.main_http と連携し、クライアントは http://<MCP_HOST>:<MCP_PORT>/sse に接続します。インストールとホストパスの説明は docs/agent-skills.md を参照してください。

機能概要

ツールは業務に応じて 9つのカテゴリ に分類されています（tools_catalog / tool_metadata と一致）：

推奨：まずツール tools_catalog（引数なし）を呼び出してカテゴリとツールリストを取得し、必要に応じて具体的なツールを呼び出してください。 証券コード形式：上海・深センなどは通常 600519.SH、000001.SZ（大文字の市場サフィックス）を使用します。

リポジトリ構造（本プロジェクト関連）

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

実行前提

1. ローカル環境で TdxQuant / 通達信 ターミナル（戦略機能を含む）が正常に動作し、公式の説明に従って戦略パスが設定されていること。

2. プロジェクトディレクトリ内の tqcenter.py がインポート可能であること（TPythClient.dll 等のパスと一致、TdxQuantドキュメントを参照）。

3. TQ_PATH が設定されていること（tq.initializeの要件に従い、戦略スクリプトのパスを指す）。

4. 依存関係と実行コマンドの管理には uv を推奨します。

インストール

uv sync

HTTP/SSE方式にはASGI依存関係が必要です：

uv sync --extra http

開発とテスト：

uv sync --extra dev

通達信クオンツオンラインヘルプミラー（help.tdx.com.cn/quant/docs/ 下のページをクロールし、ローカルMarkdownを生成、オプション）：

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

出力ディレクトリのデフォルトは docs/mirror-tdx-quant-help/ です（pages/、_manifest.json、README.md を含む）。詳細はディレクトリ内の説明を参照してください。本文の著作権は通達信に帰属します。オンライン版を正としてください。

環境変数

.env.example を .env にコピーして修正してください：

MCPプロセス起動時に get_settings() が読み込まれます。TQ_PATH が欠落していると直接エラーになります。

CursorでのMCP設定（stdio）

プロジェクト内にサンプル .cursor/mcp.json（uv + envFile）を提供しています。Cursorで本リポジトリのルートディレクトリを開いた後、設定 → MCP で tdxquant を有効にしてください。

より詳細な説明（Claude Desktop、envインライン、HTTP/SSE、トラブルシューティングを含む）は docs/mcp-configuration.md を参照してください。

起動方法

stdio（推奨：Cursor、Claude Desktopなど）

uv run python -m tdx_mcp.main_stdio

HTTP / SSE（独立プロセス、リモートMCPをサポートするクライアント用）

uv run python -m tdx_mcp.main_http

リスニングアドレスとポートは MCP_HOST / MCP_PORT によって決定されます（.envを参照）。

ツール名と呼び出し例

以下の名称はコード内の @mcp.tool(name="...") と完全に一致します。クライアントによってJSONフィールドが tool / name / toolName となる場合があります。使用するクライアントのドキュメントに従ってください。

ツールカタログの取得

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

相場：直近60日線

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

株式情報：拡張情報

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

セクター：構成銘柄

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

財務：報告期間別

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

取引：注文プレビュー（dry-run、デフォルト）

実際に注文する場合は dry_run を false に設定してください。リスクは自己責任となります。account_id は通常 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
  }
}

ツール：通達信数式の実行

メインエントリーは utility_formula_run です。別名として formula_run もあり、動作は同じです。

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

テスト

ユニットテスト（クライアント接続なし）

uv run pytest tests/ -q

連携テスト用の環境変数が設定されていない場合、統合テストケースはスキップされ、パラメータやディレクトリなどのユニットテストのみが実行されます。

統合テスト（通達信へのログインが必要）

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：オプション。データが空の場合に失敗します（デフォルトでは接続確認を容易にするため空のdictを許可）。

• TDX_TRADE_ACCOUNT：オプション。取引関連の連携テスト用アカウント文字列。

スクリプト例（MCP以外）

tdxdata_test.py は tqcenter.tq を直接呼び出す例であり、インターフェースの動作確認用です。MCPプロセスとは独立しています。

トラブルシューティング

ライセンスと上流

動作とデータ形式は TdxQuant / 通達信 および tqcenter.py に準拠します。本リポジトリはMCPラッパーとドキュメントの整理のみを行っています。