tzzb-mcp

Tonghuashun Investment Ledger MCP Server

Query personal multi-account position details, asset trends, trade records, real-time quotes, and watchlists via MCP (Model Context Protocol). Once connected to an AI assistant (such as WorkBuddy), you can query your investment ledger data directly in natural language.

Features

• 13 MCP tools, covering login authentication, accounts, positions, trends, trades, quotes, exchange rates, trading days, and watchlist queries

• Multi-account support: brokerage accounts, manual accounts, and margin accounts (distinguished by fund_key / manual_id / rzrq_fund_key)

• CDP browser proxy: all API requests are executed in the browser via Chrome DevTools Protocol, reusing the browser's native network stack to bypass the 401 anti-scraping block on direct Python connections

• Dedicated Chrome Profile (~/.tzzb_chrome_profile), does not affect your daily browser usage

• Cookie persistence (~/.tzzb_cookies.json), login once and stay authenticated for about 7 days without re-login

• Automatic reconnection on disconnect: automatically reconnects and retries once when the CDP connection drops

Related MCP server: Stock MCP Server

Requirements

• Python ≥ 3.10

• Chrome browser installed

Installation

cd tzzb-mcp
pip install .

Dependencies: mcp>=1.0.0, websocket-client>=1.8.0, pydantic>=2.0.0.

After installation, start the service with the tzzb-mcp command (entry point defined in [project.scripts] in pyproject.toml).

MCP Configuration

Connect via stdio in an MCP client (such as WorkBuddy's mcp.json):

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

cwd must point to the project directory (the directory containing src/).

Quick Start

You must call tzzb_login first on first use: this tool launches a Chrome debugging instance, and you need to log in to the investment ledger (tzzb.10jqka.com.cn) in the browser. After a successful login, the Cookie is automatically extracted and persisted.

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

Daily queries:

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

Tool List

⭐ Marks the most commonly used tools.

Usage Rules and Notes

• No parallel calls: all tools share the same Chrome CDP connection (a global lock is used underneath), so only one tool can be called at a time. Call them serially.

• Get the account list before querying positions: the fund_key / manual_id parameters of tzzb_positions come from tzzb_account_list; when no parameters are passed, aggregated data for all accounts is returned (may be empty).

• Quote format is market:code: Shanghai uses 33 (e.g. 33:600519), Shenzhen uses 47 (e.g. 47:000001). In position data, the market field value "2" corresponds to Shanghai (33), and "1" corresponds to Shenzhen (47).

• Fund position API unavailable: the fund field returned by tzzb_positions is always {"error": "基金持仓接口不可用"} (the underlying API returns HTTP 400, and built-in protection is included). Ignore the fund field and only use the stock data.

• Field names are pinyin abbreviations: quotes return xianjia (current price), zuoshou (previous close), zqdm (code), scdm (market); map them to Chinese when displaying.

• Numeric fields may be strings: numeric values in positions/quotes (e.g. "300", "18.09") are of string type; convert them when using.

• Date format YYYYMMDD: the date returned by asset trends is YYYYMMDD (e.g. 20260827); convert to YYYY-MM-DD when displaying.

• Automatic retry on disconnect: if a tool call fails (CDP connection dropped), just retry once; the underlying layer reconnects automatically. If it fails twice in a row, call tzzb_login to re-authenticate.

Technical Architecture

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

• Dedicated Chrome Profile: ~/.tzzb_chrome_profile

• Cookie persistence: ~/.tzzb_cookies.json (valid for about 7 days)

• Global lock ensures serial calls; CDP reconnects automatically on disconnect

Directory Structure

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

Troubleshooting Guide

License

Apache License 2.0