tzzb-mcp

동화순 투자 장부 MCP 서비스 (Tonghuashun Investment Ledger MCP Server)

MCP(Model Context Protocol)를 통해 개인 다중 계좌의 보유 내역, 자산 추이, 거래 기록, 실시간 시세 및 관심 목록을 조회합니다. AI 어시스턴트(예: WorkBuddy)에 연동한 후 자연어로 투자 장부 데이터를 조회할 수 있습니다.

기능 특징

• 13개의 MCP 도구: 로그인 인증, 계좌, 보유, 추이, 거래, 시세, 환율, 거래일, 관심 목록 조회를 포괄

• 다중 계좌 지원: 증권사 계좌, 수동 계좌, 신용거래 계좌(fund_key / manual_id / rzrq_fund_key로 구분)

• CDP 브라우저 프록시: 모든 API 요청이 Chrome DevTools Protocol을 통해 브라우저 내에서 실행되며, 브라우저의 네이티브 네트워크 스택을 재사용하여 Python 직접 연결 시 발생하는 401 안티크롤링 차단을 우회

• 독립 Chrome Profile(~/.tzzb_chrome_profile): 일상적인 브라우저 사용에 영향 없음

• Cookie 영속화(~/.tzzb_cookies.json): 한 번 로그인하면 약 7일간 재로그인 불필요

• 연결 끊김 자동 재연결: CDP 연결이 끊기면 자동으로 한 번 재연결을 시도

Related MCP server: Stock MCP Server

환경 요구 사항

• Python ≥ 3.10

• Chrome 브라우저 설치 필요

설치

cd tzzb-mcp
pip install .

의존성: mcp>=1.0.0, websocket-client>=1.8.0, pydantic>=2.0.0.

설치 후 tzzb-mcp 명령어로 서비스를 시작할 수 있습니다(진입점은 pyproject.toml의 [project.scripts]에 정의).

MCP 설정

MCP 클라이언트(예: WorkBuddy의 mcp.json)에서 stdio 방식으로 연동합니다:

{
  "mcpServers": {
    "tzzb-mcp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/tzzb-mcp"
    }
  }
}

cwd는 프로젝트 디렉터리(src/가 포함된 디렉터리)를 가리켜야 합니다.

빠른 시작

최초 사용 시 반드시 tzzb_login을 먼저 호출해야 합니다: 이 도구는 Chrome 디버그 인스턴스를 시작하며, 브라우저에서 투자 장부(tzzb.10jqka.com.cn)에 로그인해야 합니다. 로그인 성공 후 Cookie가 자동으로 추출되어 영속화됩니다.

1. tzzb_login          → 弹出 Chrome，手动登录投资账本
2. tzzb_account_list   → 获取所有账户的 fund_key / manual_id
3. tzzb_positions      → 查看持仓明细

일상적인 조회:

1. tzzb_account_list   → 获取账户列表
2. tzzb_positions      → 查看具体持仓
3. tzzb_asset_trend    → 查看收益走势（可选）

도구 목록

⭐ 표시는 가장 자주 사용되는 도구입니다.

사용 규칙 및 주의사항

• 병렬 호출 금지: 모든 도구가 동일한 Chrome CDP 연결을 공유하며(내부에 전역 잠금 존재), 한 번에 하나의 도구만 호출할 수 있으므로 직렬로 호출하세요.

• 보유 내역 조회 전 계좌 목록 먼저: tzzb_positions의 fund_key / manual_id 파라미터는 tzzb_account_list에서 가져옵니다. 파라미터를 전달하지 않으면 모든 계좌의 집계 데이터를 반환합니다(비어 있을 수 있음).

• 시세 형식은 시장:코드: 상해는 33(예: 33:600519), 심천은 47(예: 47:000001). 보유 데이터의 market 필드 "2"는 상해(33), "1"은 심천(47)에 해당합니다.

• 펀드 보유 인터페이스 사용 불가: tzzb_positions가 반환하는 fund 필드는 항상 {"error": "基金持仓接口不可用"}입니다(기본 인터페이스가 HTTP 400을 반환하며 내장 보호 기능이 있음). fund 필드는 무시하고 stock 데이터만 사용하세요.

• 필드명은 병음 약어: 시세는 xianjia(현재가), zuoshou(전일 종가), zqdm(코드), scdm(시장)을 반환하며, 표시 시 한글로 매핑해야 합니다.

• 숫자 필드가 문자열일 수 있음: 보유/시세의 숫자 값(예: "300", "18.09")은 문자열 타입이므로 사용 시 변환에 주의하세요.

• 날짜 형식 YYYYMMDD: 자산 추이가 반환하는 date는 YYYYMMDD 형식(예: 20260827)이며, 표시 시 YYYY-MM-DD로 변환하세요.

• 연결 끊김 자동 재시도: 도구 호출 실패(CDP 연결 끊김) 시 한 번만 재시도하면 되며, 내부적으로 자동 재연결됩니다. 연속 두 번 실패하면 tzzb_login을 호출하여 재인증해야 합니다.

기술 아키텍처

AI 助手（MCP Client）
      │  stdio
      ▼
tzzb-mcp（MCP Server, Python）
      │  Chrome DevTools Protocol :9222
      ▼
Chrome 浏览器（独立 Profile）
      │  浏览器原生 fetch（携带 Cookie）
      ▼
同花顺投资账本 API（tzzb.10jqka.com.cn）

• CDP 디버그 포트: 9222

• 독립 Chrome Profile: ~/.tzzb_chrome_profile

• Cookie 영속화: ~/.tzzb_cookies.json(유효 기간 약 7일)

• 전역 잠금으로 직렬 호출 보장, CDP 연결 끊김 시 자동 재연결

디렉터리 구조

tzzb-mcp/
├── pyproject.toml        # 项目配置与依赖
├── src/
│   ├── server.py         # MCP 服务入口（工具注册）
│   ├── auth.py           # 登录、Cookie 提取与持久化
│   ├── client.py         # Chrome CDP 连接与请求代理
│   ├── models.py         # 数据模型
│   └── api/              # 各业务接口封装
│       ├── account.py    # 账户列表 / 总览
│       ├── position.py   # 持仓明细
│       ├── market.py     # 行情 / 汇率 / 交易日
│       ├── trade.py      # 交易记录 / 分时收益 / 资产趋势
│       └── watchlist.py  # 自选列表
└── SKILL.md              # AI 助手使用技能文档（工具详细说明）

문제 해결 가이드

License

Apache License 2.0