tbank-mcp

# T-Bank MCP

<!-- mcp-name: io.github.icyberdeveloper/tbank-mcp -->

**T-Bank (Т-Банк) MCP** — mobile banking API server for Claude Code, Codex, ChatGPT, and other MCP-capable agents.

[![PyPI](https://img.shields.io/pypi/v/tbank-mcp?style=flat-square)](https://pypi.org/project/tbank-mcp/)
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=tbank&config=eyJjb21tYW5kIjoidGJhbmstbWNwIn0%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522tbank%2522%252C%2522command%2522%253A%2522tbank-mcp%2522%257D)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522tbank%2522%252C%2522command%2522%253A%2522tbank-mcp%2522%257D)

The buttons register the `tbank-mcp` command — run `pip install tbank-mcp` first.

## Demo

[**Watch the 3-minute demo (RU)**](https://youtu.be/hNpeYKgGI5k) — Claude Code shows masked card details, finds subscriptions in statements, catches a wrong SBP transfer recipient and cancels, orders groceries with checkout, and buys cinema tickets. Real session, only the waits are sped up.

## Features

- **90 tools**: accounts, cards, documents, operations, grocery ordering, cinema and
  concert tickets, train and flight booking, hotel search, orders, transfers
  (including payment by bank requisites, from a scanned invoice QR), messenger,
  investments
- **A skill for every vertical**, entered through the `tbank` router skill: grocery
  order, tickets, travel, transfer, bill pay, cards & documents, messenger, budget
  analysis, invest advisor, login
- **Pinned CA trust**: system store + the Russian Trusted Root CA (Минцифры), which no
  OS ships and every `*.t-bank-app.ru` host needs — that is most of the hosts this
  MCP talks to. Shipped in `tbank_mcp/ca/roots/`, pinned by SHA-256. Leaf/intermediate rotation
  needs no action; a root rotation is a PEM drop into `tbank_mcp/ca/roots/` (or `TBANK_EXTRA_CA`).
  The verify bundle is (re)generated from that material into
  `~/.local/share/tbank-mcp/bundle.pem`; `TBANK_CA_BUNDLE` relocates it — it is a
  write target, not a curated input, so extra roots go in via `TBANK_EXTRA_CA`.
  Certificates are never learned from the network — see the header of `tbank_mcp/tls.py`.
- **Grocery checkout**: search → cart → order → pay (proven end-to-end)
- **Secure login**: password/PIN stay OUT of the LLM context (local CLI or env var)

## Quick Install

### As a Claude Code plugin (server + every skill in one step)

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

There is no store to be admitted to — a marketplace is just a git repo with a
`.claude-plugin/marketplace.json`, and anyone can host one.

The venv and the Python dependencies are created on the server's first start by
`bin/tbank-mcp`: a plugin manifest cannot run install steps (`install` is not a
field in the schema), so the launcher does it once and every later start goes
straight to the server. Only the grocery checkout needs a browser, and 150 MB is
not something to download behind your back — install it yourself if you want that
flow:

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

### From PyPI

```bash
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
```

The `tbank-mcp` console script starts the stdio server; the pinned CA roots, the
flows reference and the skills all ship inside the wheel, so it runs from anywhere.
`tbank-mcp-login` is the same login CLI as the repo's `login_cli.py` — both write
the session to the same file the server reads. `tbank-mcp-skills` installs the
skills for Claude Code (default `~/.claude/skills`, `--target` for elsewhere) and,
unlike a plain `cp`, first removes stale copies under retired names — re-run it
after upgrades. The grocery checkout browser stays opt-in here too:
`python -m playwright install chromium`.

### Manually (clone, no plugin)

```bash
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
```

## 🔒 Login — the password never reaches the agent

The password and the PIN are secrets, and they are **not put into the model's
context**. Logging in is done by a local script, or through an environment variable.

### Option 1 (recommended): the local CLI

The script asks for the password itself, via `getpass`, so it is never echoed to the
terminal and never passes through the agent. Its prompts are in Russian, as shown:

```bash
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 читает этот же файл — путь совпадает без ручной настройки.
```

Or with the password in the environment, for CI and scripts:

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

Then **start Claude Code**. The agent picks up the saved session and works without
the password, which never enters the LLM context.

### Option 2: through the agent (convenient, but the LLM sees the password)

If you are content to hand the password to the agent:

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

⚠️ **Note:** the password ends up in the model's context and in call logs. For an
account you care about, use Option 1.

Both options need the SMS code typed in either way, so there is no unattended
login. `TBANK_PASSWORD` (and `TBANK_PIN`) are read **only** by the login CLI
(`tbank-mcp-login` / `login_cli.py`) — the
env example above — and never by the MCP server or the LLM. `TBANK_PHONE` is not
read anywhere: the phone is always a command-line argument.

> **Работа с MyT (рабочий календарь и парковка) переехала** в отдельный MCP:
> [tbank-myt](https://github.com/icyberdeveloper/tbank-myt). Другой аккаунт, другая
> сессия, свой `login_cli.py` — здесь их больше нет.

## Other agents (Codex, ChatGPT, Hermes, OpenClaw)

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

With a `pip install tbank-mcp` the whole entry shrinks to `"command": "tbank-mcp"` —
no paths, no cwd.

### Use with Cursor

Click the **Install MCP Server** button above, or open the **Customize** page from
Cursor's sidebar to add the server, or create `~/.cursor/mcp.json` (global) /
`.cursor/mcp.json` (per-project):

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

Cursor renders MCP elicitation, so the payment-confirmation buttons work in chat.

### Use with Cherry Studio

**Settings → MCP → MCP Servers → Add**: type `stdio`, command `tbank-mcp`, no
arguments. Save, enable the server, wait for the healthy status.

> Cherry Studio does not render MCP elicitation yet (open request
> [CherryHQ/cherry-studio#9145](https://github.com/CherryHQ/cherry-studio/issues/9145)),
> so reading works but the money tools refuse to execute there — by design, not by
> accident.

### Use with Goose

CLI: `goose configure` → **Add Extension** → **Command-line Extension**, name
`tbank`, command `tbank-mcp`. Desktop: sidebar → **Extensions** → **Add custom
extension**, same values.

Goose renders elicitation in both Desktop and CLI; its confirmation forms time out
after 5 minutes, so answer payment confirmations promptly.

Reading works in any MCP client. **Paying needs a client that renders MCP
elicitation** — the money tools confirm the sum with a button the user presses
(«Перевести/Отмена», «Оплатить …?»), and a client without that capability is refused
before anything is sent (`grocery_checkout` refuses there at any threshold; its
`dry_run=True` preview, which creates nothing, still works). Hermes/Telegram and
Claude Code (≥ 2.1.76) render it; Claude Desktop does not. See
`TBANK_CONFIRM_ABOVE` under Security.

## Tools

Each tool's docstring is the reference — this table is only a map of the surface.
The docstrings, the skills and everything the tools print are in Russian: the bank is
Russian and so is the person reading the answer.

| Group | Tools |
|---|---|
| **Login** | `login`, `confirm_otp`, `confirm_password`, `confirm_pin` |
| **Session** | `refresh_session`, `session_status`, `keepalive`, `push_unread_count` |
| **Reads** | `list_accounts`, `list_operations`, `spending_categories`, `operations_histogram`, `get_data` |
| **Cards & accounts** | `list_cards`, `card_limits`, `card_requisites`, `card_operations`, `account_requisites` |
| **Documents** | `documents`, `bank_documents`, `insurance_policies`, `payment_receipt` |
| **Grocery** | `grocery_stores`, `grocery_search`, `grocery_plan_order`, `grocery_add_to_cart