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, используя собственный сетевой стек браузера, что позволяет обойти блокировку 401 при прямом подключении через Python

• Отдельный Chrome Profile (~/.tzzb_chrome_profile), не влияет на повседневное использование браузера

• Постоянное хранение Cookie (~/.tzzb_cookies.json), повторный вход не требуется в течение примерно 7 дней после однократной авторизации

• Автоматическое переподключение: при разрыве CDP-соединения выполняется автоматическое переподключение с одной повторной попыткой

Related MCP server: Stock SDK 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 (точка входа определена в [project.scripts] файла pyproject.toml).

Конфигурация MCP

Подключение через stdio в MCP-клиенте (например, в mcp.json у WorkBuddy):

{
  "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    → 查看收益走势（可选）

Список инструментов

⭐ Отмечены наиболее часто используемые инструменты.

Правила использования и примечания

• Запрещены параллельные вызовы: все инструменты используют одно общее CDP-соединение Chrome (на нижнем уровне есть глобальная блокировка), одновременно можно вызывать только один инструмент — выполняйте вызовы последовательно.

• Перед запросом позиций получите список счетов: параметры fund_key / manual_id для tzzb_positions берутся из tzzb_account_list; если параметры не переданы, возвращаются агрегированные данные по всем счетам (могут быть пустыми).

• Формат котировок — рынок:код: Шанхайская биржа — 33 (например, 33:600519), Шэньчжэньская — 47 (например, 47:000001). В данных о позициях поле market со значением "2" соответствует Шанхаю (33), "1" — Шэньчжэню (47).

• API позиций по фондам недоступен: поле fund в ответе tzzb_positions всегда равно {"error": "基金持仓接口不可用"} (базовый API возвращает 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 助手使用技能文档（工具详细说明）

Руководство по устранению неполадок

Лицензия

Apache License 2.0