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