tzzb-mcp

Servicio MCP del libro de inversiones de Tonghuashun (Tonghuashun Investment Ledger MCP Server)

Consulta el detalle de posiciones, tendencia de activos, registros de operaciones, cotizaciones en tiempo real y lista de seguimiento de múltiples cuentas personales mediante MCP (Model Context Protocol). Una vez conectado a un asistente de IA (como WorkBuddy), puedes consultar los datos de tu libro de inversiones directamente en lenguaje natural.

Características

• 13 herramientas MCP, que cubren autenticación de inicio de sesión, cuentas, posiciones, tendencias, operaciones, cotizaciones, tipos de cambio, días de negociación y consulta de lista de seguimiento

• Soporte multi-cuenta: cuentas de corredor, cuentas manuales y cuentas de margen (diferenciadas por fund_key / manual_id / rzrq_fund_key)

• Proxy de navegador CDP: todas las solicitudes de API se ejecutan en el navegador a través de Chrome DevTools Protocol, reutilizando la pila de red nativa del navegador para evitar el bloqueo anti-scraping 401 de las conexiones directas de Python

• Perfil de Chrome independiente (~/.tzzb_chrome_profile), sin afectar al uso diario del navegador

• Persistencia de cookies (~/.tzzb_cookies.json), un solo inicio de sesión evita repetir la autenticación durante aproximadamente 7 días

• Reconexión automática: cuando se interrumpe la conexión CDP, se reconecta y reintenta automáticamente una vez

Related MCP server: Stock MCP Server

Requisitos del entorno

• Python ≥ 3.10

• Navegador Chrome instalado

Instalación

cd tzzb-mcp
pip install .

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

Tras la instalación, el servicio se puede iniciar con el comando tzzb-mcp (la entrada se define en [project.scripts] de pyproject.toml).

Configuración de MCP

En el cliente MCP (como mcp.json de WorkBuddy), conéctalo mediante stdio:

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

cwd debe apuntar al directorio del proyecto (el directorio que contiene src/).

Inicio rápido

En el primer uso, es obligatorio llamar a tzzb_login: esta herramienta inicia una instancia de depuración de Chrome; debes iniciar sesión en el libro de inversiones (tzzb.10jqka.com.cn) en el navegador. Tras iniciar sesión correctamente, las cookies se extraen y persisten automáticamente.

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

Consultas diarias:

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

Lista de herramientas

⭐ Marcadas como las herramientas más utilizadas.

Reglas de uso y notas

• Prohibido el uso en paralelo: todas las herramientas comparten la misma conexión CDP de Chrome (hay un bloqueo global subyacente); solo se puede llamar a una herramienta a la vez, hazlo de forma secuencial.

• Obtén primero la lista de cuentas para consultar posiciones: los parámetros fund_key / manual_id de tzzb_positions provienen de tzzb_account_list; si no se pasan parámetros, se devuelven los datos agregados de todas las cuentas (puede estar vacío).

• Formato de cotización mercado:código: la Bolsa de Shanghái usa 33 (p. ej. 33:600519), la Bolsa de Shenzhen usa 47 (p. ej. 47:000001). En los datos de posiciones, el campo market con valor "2" corresponde a Shanghái (33) y "1" a Shenzhen (47).

• Interfaz de posiciones de fondos no disponible: el campo fund devuelto por tzzb_positions siempre es {"error": "基金持仓接口不可用"} (la interfaz subyacente devuelve HTTP 400, ya protegido internamente); ignora el campo fund y usa solo los datos de stock.

• Los nombres de campos son abreviaturas pinyin: las cotizaciones devuelven xianjia (precio actual), zuoshou (cierre anterior), zqdm (código), scdm (mercado); al mostrarlos, hay que mapearlos al chino.

• Los campos numéricos pueden ser cadenas: los valores numéricos en posiciones/cotizaciones (como "300", "18.09") son de tipo cadena; ten cuidado al convertirlos.

• Formato de fecha YYYYMMDD: el campo date de la tendencia de activos tiene formato YYYYMMDD (p. ej. 20260827); al mostrarlo, conviértelo a YYYY-MM-DD.

• Reintento automático tras desconexión: si una llamada a herramienta falla (conexión CDP interrumpida), basta con reintentar una vez; la capa subyacente se reconecta automáticamente. Si falla dos veces seguidas, llama a tzzb_login para volver a autenticarte.

Arquitectura técnica

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

• Puerto de depuración CDP: 9222

• Perfil de Chrome independiente: ~/.tzzb_chrome_profile

• Persistencia de cookies: ~/.tzzb_cookies.json (validez aproximada de 7 días)

• Bloqueo global para garantizar llamadas secuenciales; reconexión automática si se interrumpe el CDP

Estructura de directorios

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

Guía de resolución de problemas

Licencia

Apache License 2.0