TdxQuant MCP Сервер

Оболочка MCP (Model Context Protocol), основанная на локальном tqcenter.py (интерфейс стратегий TdxQuant / TongDaXin). AI-клиенты (например, Cursor) могут вызывать инструменты через stdio или HTTP/SSE для получения данных о котировках, финансах, секторах, формулах и т.д.

Имя Python-пакета: tdxquant-mcp (см. pyproject.toml).

Подключение MCP: docs/mcp-configuration.md Использование агента (порядок вызовов, сопоставление намерений, безопасность торговли): 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 и фрагменты конфигурации SSE в references/, а также упрощенные рабочие процессы). При запущенном 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 / TongDaXin (с поддержкой стратегий), и путь к стратегиям должен быть настроен согласно официальной инструкции.

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

Зеркало онлайн-справки TdxQuant (парсинг страниц 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). Подробности см. в описании внутри этого каталога; авторские права на текст принадлежат TongDaXin, пожалуйста, сверяйтесь с онлайн-версией.

Переменные окружения

Скопируйте .env.example в .env и внесите изменения:

При запуске процесса MCP загружается get_settings(), отсутствие TQ_PATH приведет к ошибке.

Настройка MCP в Cursor (stdio)

В проекте предоставлен пример .cursor/mcp.json (uv + envFile). После открытия корня репозитория в Cursor, включите tdxquant в разделе Настройки → MCP.

Более полные инструкции (включая 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
  }
}

Инструменты: выполнение формул TongDaXin

Основная точка входа — 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

Если переменные окружения для интеграционного тестирования не заданы, интеграционные тесты будут пропущены, выполняются только модульные тесты параметров, каталогов и т.д.

Интеграционное тестирование (требуется вход в TongDaXin)

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 / TongDaXin и tqcenter.py; данный репозиторий является лишь оболочкой MCP и систематизацией документации.