T-Bank MCP

T-Bank MCP

T-Bank (Т-Банк) MCP — 面向 Claude Code、Codex、ChatGPT 及其他支持 MCP 的 Agent 的移动银行 API 服务。

这些按钮会注册 tbank-mcp 命令——请先运行 pip install tbank-mcp。

功能

• 90 个工具：账户、银行卡、文档、交易、杂货订购、电影和音乐会门票、火车票和机票预订、酒店搜索、订单、转账（包括使用银行账户信息付款、扫描发票二维码付款）、即时通讯、投资
• 每个业务领域都有一个技能，通过 tbank 路由技能进入：杂货订单、门票、旅行、转账、账单支付、银行卡和文档、即时通讯、预算分析、投资顾问、登录
• 固定 CA 信任：系统证书库 + 俄罗斯受信任根 CA（Минцифры）；操作系统均未内置该证书，而每个 *.t-bank-app.ru 主机都需要它——这也是此 MCP 通信的大多数主机。证书随包提供于 tbank_mcp/ca/roots/，并通过 SHA-256 固定。叶证书和中间证书轮换无需任何操作；根证书轮换时，只需将 PEM 文件放入 tbank_mcp/ca/roots/（或设置 TBANK_EXTRA_CA）。验证证书包会根据这些材料生成或重新生成到 ~/.local/share/tbank-mcp/bundle.pem；TBANK_CA_BUNDLE 可更改其位置——它是写入目标，而不是用于整理证书的输入位置，因此额外的根证书应通过 TBANK_EXTRA_CA 添加。证书绝不会从网络获取——请参见 tbank_mcp/tls.py 的文件头注释。
• 杂货结账：搜索 → 购物车 → 订单 → 付款（已通过端到端验证）
• 安全登录：密码和 PIN 不会进入大模型上下文（通过本地 CLI 或环境变量输入）

快速安装

作为 Claude Code 插件（一步安装服务端和全部技能）

/plugin marketplace add icyberdeveloper/tbank-mcp
/plugin install tbank@tbank-mcp
/reload-plugins

无需申请加入任何商店——市场只是一个带有 .claude-plugin/marketplace.json 的 git 仓库，任何人都可以托管。

虚拟环境和 Python 依赖项会在服务首次启动时由 bin/tbank-mcp 创建：插件清单无法执行安装步骤（架构中没有 install 字段），因此启动器会执行一次，之后每次启动都会直接运行服务。只有杂货结账需要浏览器；150 MB 的文件不应在你不知情时下载——如果需要使用该流程，请自行安装：

~/.claude/plugins/cache/tbank-mcp/tbank/*/.venv/bin/python -m playwright install chromium

从 PyPI 安装

pip install tbank-mcp
tbank-mcp-login +7XXXXXXXXXX   # first login: SMS code + password in YOUR terminal, not the LLM
claude mcp add tbank -- tbank-mcp
tbank-mcp-skills               # optional: the Claude Code skills, into ~/.claude/skills

tbank-mcp 控制台脚本会启动 stdio 服务；固定的 CA 根证书、流程参考文档和技能都包含在 wheel 中，因此可从任意位置运行。tbank-mcp-login 与仓库中的 login_cli.py 是同一个登录 CLI——两者都会将会话写入服务读取的同一文件。tbank-mcp-skills 会为 Claude Code 安装技能（默认安装到 ~/.claude/skills，也可使用 --target 指定其他位置），与直接使用 cp 不同，它会先删除已弃用名称下的旧副本——升级后请重新运行。这里的杂货结账浏览器同样需要选择安装： python -m playwright install chromium

手动安装（克隆，不使用插件）

git clone https://github.com/icyberdeveloper/tbank-mcp.git
cd tbank-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e .
python -m playwright install chromium

# MCP server:
claude mcp add tbank -- ./.venv/bin/python -m tbank_mcp.server

# Skills — a COPY, so it does not follow the repo. Re-run after every pull, or
# the installed skills quietly describe an older version of these tools. The
# installer also removes stale copies under RENAMED skill names, which a plain
# cp never does — the agent would keep loading the stale one:
.venv/bin/tbank-mcp-skills

🔒 登录——密码绝不会传给 Agent

密码和 PIN 都是机密，不会放入大模型的上下文中。登录通过本地脚本或环境变量完成。

选项 1（推荐）：本地 CLI

脚本会通过 getpass 自行请求密码，因此密码不会显示在终端中，也不会经过 Agent。提示信息为俄语，如下所示：

cd tbank-mcp

.venv/bin/python login_cli.py +7XXXXXXXXXX
# [1/3] login(+7XXXXXXXXXX) ...
#     SMS отправлена
# [2/3] SMS-код: ****                     ← the code from the SMS (hidden input)
# [3/3] Пароль (не отображается): ****    ← your password (hidden input)
#
# ✓ ГОТОВО! Сессия сохранена: ~/.local/share/tbank-mcp/session.json (права 0600).
#   MCP читает этот же файл — путь совпадает без ручной настройки.

也可以将密码设为环境变量，用于 CI 和脚本：

TBANK_PASSWORD="your-password" .venv/bin/python login_cli.py +7XXXXXXXXXX

然后启动 Claude Code。Agent 会使用已保存的会话，无需密码即可工作；密码不会进入大模型上下文。

选项 2：通过 Agent 操作（方便，但大模型会看到密码）

如果你愿意将密码交给 Agent：

> login(+7XXXXXXXXXX)
> [SMS code] 1234
> confirm_otp("1234")
> [bank asks password]
> confirm_password("YourPassword")

⚠️ **注意：**密码会进入模型上下文和调用日志。如果你在意账户安全，请使用选项 1。

无论采用哪种方式，都需要手动输入短信验证码，因此无法实现无人值守登录。TBANK_PASSWORD（以及 TBANK_PIN）仅由登录 CLI（tbank-mcp-login / login_cli.py）读取——即上方环境变量示例中的方式——MCP 服务和大模型都不会读取这些变量。任何地方都不会读取 TBANK_PHONE：电话号码始终作为命令行参数传入。

MyT（工作日历和停车）已迁移至独立的 MCP： tbank-myt。它使用另一个账户、另一个会话和自己的 login_cli.py——这里已不再包含这些内容。

其他 Agent（Codex、ChatGPT、Hermes、OpenClaw）

{
  "mcpServers": {
    "tbank": {
      "command": "/path/to/tbank-mcp/.venv/bin/python",
      "args": ["-m", "tbank_mcp.server"],
      "cwd": "/path/to/tbank-mcp"
    }
  }
}

通过 pip install tbank-mcp 安装后，整个条目可简化为 "command": "tbank-mcp"——无需路径和 cwd。

与 Cursor 搭配使用

点击上方的 Install MCP Server 按钮，或在 Cursor 侧边栏中打开 Customize 页面添加服务；也可以创建 ~/.cursor/mcp.json（全局）/ .cursor/mcp.json（每个项目独立）：

{
  "mcpServers": {
    "tbank": { "command": "tbank-mcp" }
  }
}

Cursor 支持呈现 MCP elicitation，因此付款确认按钮可以在聊天中正常使用。

与 Cherry Studio 搭配使用

Settings → MCP → MCP Servers → Add：输入 stdio，命令填写 tbank-mcp，不添加参数。保存并启用服务，然后等待状态显示正常。

Cherry Studio 目前尚不支持呈现 MCP elicitation（可关注待处理请求 CherryHQ/cherry-studio#9145）， 因此可以读取信息，但其中的资金工具会拒绝执行——这是有意为之，并非意外情况。

与 Goose 搭配使用

CLI：goose configure → Add Extension → Command-line Extension，名称填写 tbank，命令填写 tbank-mcp。桌面版：侧边栏 → Extensions → Add custom extension，填写相同的值。

Goose 在桌面版和 CLI 中都支持呈现 elicitation；其确认表单会在 5 分钟后超时，因此请及时确认付款。

在任何 MCP 客户端中都可以读取信息。付款需要使用支持呈现 MCP elicitation 的客户端——资金工具会通过按钮让用户确认金额（“转账/取消”、“付款……？”）；不具备此功能的客户端会被拒绝执行，且不会发送任何内容（grocery_checkout 在此类客户端中无论阈值如何都会拒绝执行；不会创建任何内容的 dry_run=True 预览仍可使用）。Hermes/Telegram 和 Claude Code（≥ 2.1.76）支持呈现；Claude Desktop 不支持。请参阅安全部分中的 TBANK_CONFIRM_ABOVE。

工具

每个工具的文档字符串都是参考依据——此表仅概述可用工具。 文档字符串、技能以及工具输出的所有内容均为俄语：银行在俄罗斯，阅读答案的人也在俄罗斯。

分组	工具
登录	login, confirm_otp, confirm_password, confirm_pin
会话	refresh_session, session_status, keepalive, push_unread_count
读取	list_accounts, list_operations, spending_categories, operations_histogram, get_data
银行卡和账户	list_cards, card_limits, card_requisites, card_operations, account_requisites
文档	documents, bank_documents, insurance_policies, payment_receipt
杂货	grocery_stores, grocery_search, grocery_plan_order, grocery_add_to_cart, grocery_set_cart, grocery_cart, grocery_checkout, payment_attempts, grocery_order_status, grocery_order_cancel
营养	grocery_good_info, grocery_rank
订单	orders, order_details, travel_order_details
演出资讯	afisha_catalog, afisha_places, place_schedule, place_info
票务	cinema_search, cinema_schedule, cinema_seats, concert_schedule, concert_hall, cinema_book, ticket_pay, ticket_cancel, ticket_qr
搜索	search_app
旅行搜索	train_search, train_calendar, flight_search, flight_offer, flight_history
旅行预订	train_seats, train_book, train_pay, train_refund, flight_seats, flight_book
酒店	hotel_search, hotel_info
行程	trips, travel_payment_options, travel_ticket_file
商城	shop_search, shop_cart
消息	messenger_conversations, messenger_messages, messenger_file, messenger_send, messenger_unread
资金	transfer_sbp_resolve, transfer, payment_qr, transfer_requisites, payment_commission, pay_bill, payment_providers, confirm_payment, payment_status
投资	invest_accounts, invest_portfolio, invest_operations, invest_securities
实用工具	flows, diagnostics, debug_report

get_data(section) 覆盖数十个读取类分区：订阅、credit_schedule、对账单、贷款、invest_accounts、养老金等。（invest_portfolio 是独立工具，不是分区——完整列表请参阅文档字符串。）

杂货工具（grocery_search、grocery_plan_order、grocery_add_to_cart、grocery_set_cart、grocery_cart、grocery_checkout）需要使用从 grocery_stores() 获取的 app_id + point_id——不会静默使用默认商店，因此添加商品、查看购物车和结账始终针对同一个购物车，避免商品添加到另一家商店后购物车却显示为空。

技能

技能	功能
tbank	入口——介绍银行能做什么，以及由哪个技能处理
tbank-grocery-order	食谱 → 搜索 → 购物车 → 展示购物车 → 结账（工具自身的按钮会确认总金额）
tbank-tickets	电影院／音乐会：搜索 → 场次 → 座位 → 预订 → 支付
tbank-travel	火车和航班：搜索 → 座位 → 预订 → 支付 → 退款；酒店和商城：仅搜索
tbank-bill-pay	服务账单——公用事业费、税款、罚款：目录 → 服务商字段 → 手续费预览 → 支付
tbank-transfer-money	P2P、SBP（СБП）、账户转账
tbank-cards-documents	银行卡、限额、账户信息、护照及其他文档
tbank-messenger	银行聊天和客服支持
tbank-budget-analyzer	支出分析、订阅审核、省钱建议
tbank-invest-advisor	投资组合、盈亏、再平衡、税务优化
tbank-login	多步骤登录、会话管理

示例请求

请用俄语提问——工具会用俄语回答。以下内容均在银行的线上环境中运行。

电影和演出资讯

Что идёт в кино сегодня?
Купи два билета на «Майкла» на завтра в Каро 11 около 20:00 в центре зала
Отмени заказ
Покажи последние 5 моих заказов

资金

Покажи мои счета
Переведи 10 рублей Алёне на +79991234567
Какие последние 5 операций?
Покажи реквизиты счёта

杂货

Хочу оливье, собери корзину с минимальным КБЖУ
Хочу оливье, собери корзину с минимальной ценой
Хочу оливье, собери корзину из премиум продуктов
Найди самый дешёвый картофель за килограмм
Отмени заказ

银行卡和文档

Покажи реквизиты основной карты
Какие лимиты по основной карте?
Покажи реквизиты моего паспорта
Когда истекает мой загранпаспорт?

测试

不使用 pytest——这些测试是独立脚本。运行所有测试：

.venv/bin/python tests/run_all.py            # every file, under a minute, offline
.venv/bin/python tests/run_all.py transfer   # only files matching "transfer"

每个测试都会在独立进程中运行，运行器会将尝试记录和事件日志重定向到临时目录，因此测试运行不会写入 ~/.local/share/tbank-mcp/。

所需内容都在仓库中：请求契约以 tests/fixtures/ 中经过脱敏的固件为基准（真实结构和协议值，合成个人数据），因此在干净克隆的仓库中运行测试套件也有意义。如果存在原始 Burp 捕获，测试还会额外检查固件是否与其保持一致。

安全

• session.json——标准路径为 ~/.local/share/tbank-mcp/session.json （可通过 TBANK_SESSION 覆盖），权限模式为 0600，仅所有者可访问。文件中保存令牌。登录 CLI 和 MCP 服务读取同一个文件，因此无需进行任何配置。启动时，MCP 只记录路径、大小和权限——绝不记录令牌或 Cookie。
• 密码 / PIN——不会保存在 git 中，不会出现在代码里；如果使用登录 CLI（tbank-mcp-login / login_cli.py），也不会进入大模型上下文。
• 仓库中没有机密信息。 两类已提交的材料看起来可能与机密有关，但实际并非如此：tbank_mcp/ca/roots/*.pem 是公开的 CA 根证书，特意随项目一同分发，并在 tbank_mcp/tls.py 中通过 SHA-256 固定；tests/fixtures/*.json 是从真实捕获数据中清理出的请求契约——保留真实结构和协议值，但账号、电话、地址和设备 ID 均为合成数据。捕获数据本身已加入 gitignore，绝不会离开本机。
• events.jsonl + attempts.jsonl——位于 ~/.local/share/tbank-mcp/ 的脱敏诊断信息。记录步骤、http_status、归因、金额和订单 ID，绝不记录令牌、Cookie、地址、电话号码、电子邮件或账号。调试时可以安全地分享；diagnostics 工具会读取这些文件。
• calls.jsonl——每次工具调用占一行，用于查看 Agent 如何使用此 MCP：调用的工具、参数、耗时，以及答案的第一行，也就是 Agent 实际读取的内容。遵守与上述文件相同的承诺：人手写的自由文本参数（聊天消息、转账备注等）或凭据只会统计，不会存储；长串数字——账号、卡片、订单和支付 ID——会在记录的行中替换掉，既避免泄露，也因为报告会按该行分组。debug_report 工具会读取此文件。默认启用；设置 TBANK_TRACE=0 可禁用，设置 TBANK_TRACE_FILE 可更改文件位置，并且文件会在达到 5 MB 时轮转。
• TBANK_CONFIRM_ABOVE——用于设置触发确认按钮的卢布金额门槛。该按钮适用于会立即扣款的支付工具（transfer、transfer_requisites、pay_bill、ticket_pay、grocery_checkout、train_pay、flight_book），显示为由客户端呈现的 MCP elicitation 对话框（«Перевести/Отмена»、«Оплатить …?»、«Оформить заказ на N ₽?»）。默认值为 0，即每笔支付都需要确认。这是服务端设置，不是工具参数。不支持 elicitation 的客户端不会被放行：金额达到或超过门槛时，工具会在记录日志或发送请求之前拒绝（«ПЛАТЁЖ НЕ ВЫПОЛНЕН…»）——没有按钮，也不会支付。Hermes/Telegram 和 Claude Code（≥ 2.1.76）会呈现 elicitation；Claude Desktop 不支持（可以在其中读取信息，但不能支付）。 如果门槛为正数且金额低于门槛，则不会弹出确认，支付会在任何客户端中继续执行——但 grocery_checkout 除外：无论门槛是多少，它都会拒绝不支持 elicitation 的客户端。它是唯一必须先加载结账页面才能得知总金额的支付工具，而加载页面意味着要求商家预留配送时段，因此它会在执行此操作前拒绝，而不是完成操作后再拒绝。 在任何客户端中，grocery_checkout(dry_run=True)——不会创建任何内容的预览——仍可正常使用。
• 设备配置。 支付请求包含 3DS/反欺诈信息块，其中的设备信息——屏幕尺寸、区域设置、时区、硬件型号——默认采用捕获流量时使用的设备信息。请通过 TBANK_DEVICE_SCREEN_HEIGHT / _WIDTH / TBANK_DEVICE_LANGUAGE / TBANK_DEVICE_TIMEZONE / TBANK_DEVICE_MODEL 覆盖这些值，避免支付信息描述他人的手机。
• 请求格式开关。 两处与捕获到的应用不一致的行为可通过环境变量恢复，因此回滚只需修改一个变量，无需重新登录（两者都不会修改 session.json）：
  • TBANK_QUERY_PROFILE=legacy——恢复向每个主机发送 wuid，并在每次读取时注入 vendor/client_version。应用只会向 /api/common/ 下的 www.tbank.ru 发送 wuid，并且只会在 OIDC authorize 调用时向另外两个主机发送，因此默认值现为按范围发送。
  • TBANK_ACCEPT_PROFILE——可设为 json（默认值，与当前行为逐字节一致）、auto，或以逗号分隔的主机列表。应用不会向其原生主机发送 application/json；未设置 Accept 时出现的该字符串，是 Apple URL 加载机制的默认值。捕获到的响应在两种情况下都是 application/json，因此这属于兼容性调整，而非修复问题——但 63 个模板共用最繁忙的主机，且没有预发布环境，所以该功能默认关闭，需在实际环境中逐步启用。按主机类别逐一启用，先从风险最低的开始：webview/shortcuts/my-home（无法访问或仅执行简单读取）→ api-invest*（invest_accounts、invest_portfolio）→ api.t-bank-app.ru，先测试 keepalive，其 Content-Type 已证实会变为 text/html，而响应正文仍是 JSON → www.tbank.ru → 三个生活服务货架路径。回归问题只有一种特征：_unwrap 因响应正文无法解析而抛出 HTTP_200。每一步前后都应比较 debug_report()。
• 资金工具（transfer、transfer_requisites、grocery_checkout、ticket_pay、pay_bill、train_pay、flight_book、confirm_payment）要求确认具体金额——“买吧”不算确认。确认通过工具自身显示的按钮完成（elicitation，参见上方的 TBANK_CONFIRM_ABOVE），按钮显示实际总额。Agent 会事先展示详情（收款人、账户信息、购物车、座位 + 费用），不会在文本中询问“是/否”；grocery_checkout 会自行报出最终金额，并且只会扣除按钮上显示的金额——如果报价未定价（购物车为空、商店拒绝预览，或没有有限的正数总额），它只会返回预览，不会扣款。银行将 /v1/pay 保留在 WAITING_CONFIRMATION 状态时，应通过 confirm_payment(attempt_id, otp) 恢复操作，并通过 payment_status(attempt_id) 对账——绝不能重复转账，否则会创建第二笔待处理支付。
• 工具注解。 每个工具的行为都在一个表中声明——tbank_mcp/server.py 中的 TOOL_KINDS——缺少声明的工具会在导入时触发错误，而不会使用默认值。共有三类：67 个标记为 readOnlyHint: true，无需提示即可运行；15 个会创建不产生费用的内容（购物车、预订、消息、OTP、令牌、本地文件），标记为 destructiveHint: false；8 个会扣款——transfer、transfer_requisites、grocery_checkout、ticket_pay、pay_bill、train_pay、flight_book、confirm_payment——仅这些工具带有 destructiveHint，因此主机会在运行前提示用户（金额本身随后由工具自己的 elicitation 按钮确认，见上文）。这里刻意以资金为界：预订会自动过期，购物车中的商品也可以轻易修改，因此要求确认这些操作只会增加阻碍，让人习惯于点击通过真正重要的对话框。 这 15 个会写入数据的工具不会标记为只读，因为它们确实会修改内容，而该标记表示相反的含义——如果你的客户端仍会对这些工具弹出提示，请在客户端中为其单独允许一次，而不要修改服务端的声明。

免责声明

仅供个人使用自己的 T-Bank 账户。与 T-Bank 无关联。