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 래퍼 및 문서 정리만을 제공합니다.