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）：1 回のログインで約 7 日間は再ログイン不要

• 切断時自動再接続：CDP 接続が切断された場合、自動的に再接続を 1 回試行

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 接続を共有します（内部にグローバルロックあり）。一度に呼び出せるツールは 1 つのみで、直列に呼び出してください。

• 保有照会の前に口座リストを取得：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 接続切断）、1 回リトライすれば内部で自動再接続されます。連続 2 回失敗した場合は 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