tzzb-mcp

Tonghuashun Investment Ledger MCP-Server

Über MCP (Model Context Protocol) können persönliche Positionsdetails, Vermögensentwicklung, Transaktionshistorie, Echtzeitkurse und Watchlists mehrerer Konten abgefragt werden. Nach der Anbindung an KI-Assistenten (z. B. WorkBuddy) können diese deine Investment-Ledger-Daten direkt in natürlicher Sprache abfragen.

Funktionen

• 13 MCP-Tools für Login-Authentifizierung, Konten, Positionen, Trends, Transaktionen, Kurse, Wechselkurse, Handelstage und Watchlist-Abfragen

• Multi-Konto-Unterstützung: Broker-Konten, manuelle Konten, Margin-Konten (unterschieden nach fund_key / manual_id / rzrq_fund_key)

• CDP-Browser-Proxy: Alle API-Anfragen werden über das Chrome DevTools Protocol im Browser ausgeführt und nutzen den nativen Netzwerk-Stack des Browsers, wodurch die 401-Anti-Scraping-Sperre bei direkter Python-Verbindung umgangen wird

• Separates Chrome-Profil (~/.tzzb_chrome_profile), ohne Auswirkungen auf die tägliche Browser-Nutzung

• Cookie-Persistenz (~/.tzzb_cookies.json), nach einmaligem Login ca. 7 Tage ohne erneuten Login

• Automatische Wiederverbindung bei Verbindungsabbruch: Bei getrennter CDP-Verbindung wird automatisch einmal neu verbunden

Related MCP server: Stock SDK MCP Server

Systemanforderungen

• Python ≥ 3.10

• Chrome-Browser installiert

Installation

cd tzzb-mcp
pip install .

Abhängigkeiten: mcp>=1.0.0, websocket-client>=1.8.0, pydantic>=2.0.0.

Nach der Installation kann der Dienst über den Befehl tzzb-mcp gestartet werden (Einstiegspunkt definiert in [project.scripts] der pyproject.toml).

MCP-Konfiguration

Im MCP-Client (z. B. in der mcp.json von WorkBuddy) über stdio anbinden:

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

cwd muss auf das Projektverzeichnis zeigen (das Verzeichnis, das src/ enthält).

Schnellstart

Beim ersten Mal muss zuerst tzzb_login aufgerufen werden: Dieses Tool startet eine Chrome-Debug-Instanz. Du musst dich im Browser beim Investment-Ledger (tzzb.10jqka.com.cn) anmelden. Nach erfolgreichem Login wird das Cookie automatisch extrahiert und persistiert.

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

Tägliche Abfragen:

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

Tool-Liste

⭐ markiert die am häufigsten verwendeten Tools.

Nutzungsregeln und Hinweise

• Keine parallelen Aufrufe: Alle Tools teilen sich dieselbe Chrome-CDP-Verbindung (darunter liegt eine globale Sperre). Es kann immer nur ein Tool gleichzeitig aufgerufen werden – bitte seriell aufrufen.

• Vor Positionsabfrage zuerst die Kontoliste abrufen: Die Parameter fund_key / manual_id von tzzb_positions stammen aus tzzb_account_list; ohne Parameter werden aggregierte Daten aller Konten zurückgegeben (kann leer sein).

• Kursformat Markt:Code: Shanghai verwendet 33 (z. B. 33:600519), Shenzhen verwendet 47 (z. B. 47:000001). Das Feld market in den Positionsdaten entspricht "2" für Shanghai (33) und "1" für Shenzhen (47).

• Fonds-Positionsschnittstelle nicht verfügbar: Das Feld fund von tzzb_positions ist immer {"error": "基金持仓接口不可用"} (die zugrunde liegende Schnittstelle gibt HTTP 400 zurück, ein Schutz ist eingebaut). Bitte das Feld fund ignorieren und nur die Daten aus stock verwenden.

• Feldnamen sind Pinyin-Abkürzungen: Die Kursdaten liefern xianjia (aktueller Preis), zuoshou (gestriger Schlusskurs), zqdm (Code), scdm (Markt); bei der Anzeige müssen diese in Chinesisch gemappt werden.

• Numerische Felder können Strings sein: Die numerischen Werte in Positionen/Kursen (z. B. "300", "18.09") sind vom Typ String – bei der Verwendung auf die Konvertierung achten.

• Datumsformat YYYYMMDD: Das Feld date der Vermögensentwicklung hat das Format YYYYMMDD (z. B. 20260827), bei der Anzeige in YYYY-MM-DD umwandeln.

• Automatischer Wiederholungsversuch bei Verbindungsabbruch: Wenn ein Tool-Aufruf fehlschlägt (CDP-Verbindung getrennt), einfach einmal erneut versuchen – die Verbindung wird automatisch wiederhergestellt. Bei zwei aufeinanderfolgenden Fehlschlägen muss tzzb_login zur erneuten Authentifizierung aufgerufen werden.

Technische Architektur

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

• CDP-Debug-Port: 9222

• Separates Chrome-Profil: ~/.tzzb_chrome_profile

• Cookie-Persistenz: ~/.tzzb_cookies.json (Gültigkeit ca. 7 Tage)

• Globale Sperre für serielle Aufrufe, automatische Wiederverbindung bei CDP-Abbruch

Verzeichnisstruktur

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 助手使用技能文档（工具详细说明）

Fehlerbehebung

Lizenz

Apache License 2.0