# T-Bank Personal MCP

Минимальный stdio MCP для личных счетов физлица: счета, остатки и история
операций. Использует **непубличный API мобильного банка**.
Это не официальный T-API для сторонних разработчиков. Формат мобильного API
может измениться; работоспособность с живым аккаунтом пока не проверена.

## Инструменты

- `list_accounts()` — счета и остатки одним запросом; без реквизитов карт.
- `get_balances(account_id?)` — остатки всех счетов или одного.
- `list_operations(start, end, account_id?, limit=100, offset=0)` — операции
  за период до 31 дня, даты ISO 8601 с часовым поясом. Пример:
  `2026-10-01T00:00:00+03:00` → `2026-10-06T23:59:59+03:00`.

Каждый вызов делает один запрос. Нет платежных инструментов, универсального
HTTP-инструмента, фонового опроса, keepalive, автоматического повторения запросов
или обновления сессии. При истечении сессии нужен новый локальный вход.
Суммы с дробной частью читаются как строки, без округления через float.

История фильтруется и разбивается на страницы локально. `truncated` и
`next_offset` обозначают обрезку выдачи MCP, `matching_received` — количество
подходящих операций в полученном ответе банка. `coverage=bank_completeness_unknown`
означает, что полнота ответа самого банка не подтверждена. Запрос следующей
страницы снова обращается к банку: это не фиксированный снимок. На границах
интервалов возможны дубли, учитывайте id операций. Пустой результат по account_id
не доказывает существование счёта — id нужно брать из `list_accounts`.

## Куда идут запросы

| Процесс | Разрешённые запросы |
| --- | --- |
| MCP | `GET https://api.t-bank-app.ru/v1/accounts_light` |
| MCP | `GET https://api.t-bank-app.ru/v1/operations` |
| Локальный вход | `GET https://id.t-bank-app.ru/auth/authorize` |
| Локальный вход | `POST https://id.t-bank-app.ru/auth/step` |
| Локальный вход | `POST https://id.t-bank-app.ru/auth/token/mobile` |

Список фиксирован в коде. Хосты, пути и методы нельзя переопределить через
аргументы MCP, файл сессии или переменные окружения. HTTP-редиректы запрещены,
прокси из окружения отключены. TLS проверяет имя сервера и цепочку до локально
включённого Russian Trusted Root CA с проверкой SHA-256. Системное хранилище
сертификатов не меняется, сертификаты из сети не скачиваются.

У MCP нет телеметрии, аналитики, автообновления или стороннего backend.
DNS-разрешение имён выполняет ОС через настроенный DNS-сервер. Это ограничение
HTTP-клиента, а не системный firewall для всей машины.
**Результаты инструментов передаются ChatGPT и могут попасть в историю чата.**
Условие «только банк» относится к исходящим HTTP-запросам нашего сервера и CLI,
а не к сетевой работе приложения ChatGPT.

## Установка и вход

Python 3.10+. Единственная прямая runtime-зависимость — официальный Python MCP SDK
(`mcp`). Его транзитивные зависимости зафиксированы в `uv.lock`; SDK включает
и HTTP-компоненты, хотя здесь используется только stdio. Банковский клиент и
команда входа используют стандартную библиотеку Python.

```bash
uv sync --frozen
.venv/bin/python login.py
```

Установка зависимостей обращается в реестр Python-пакетов; она выполняется
отдельно от работы MCP. Desktop запускает уже установленный Python напрямую,
без `uv run`/`uvx` и без скачивания пакетов при старте.

Без uv: `python3 -m venv .venv`, затем `.venv/bin/python -m pip install .`.
В Windows интерпретатор находится в `.venv\Scripts\python.exe`.

**Запускайте login.py самостоятельно в терминале.** Телефон вводится интерактивно,
SMS-код, пароль и PIN — скрыто, только если банк запросил соответствующий шаг.
Не отправляйте эти данные в чат. Неизвестный шаг авторизации останавливает вход.

Сессия сохраняется атомарно в
`~/.local/share/tbank-personal-mcp/session.json` (0600 на POSIX).
Путь можно изменить переменной `TBANK_SESSION`, одинаковой для CLI и сервера.
В Windows доступ к файлу определяется ACL пользовательского профиля.
Сохраняются только access token, мобильная сессия, id устройства и три допустимых
служебных cookie. Пароль, SMS-код, refresh token и SSO_SESSION не сохраняются.
Сервер перечитывает файл при каждом вызове — после нового входа перезапуск не нужен.
Банковские ответы и операции на диск не записываются.

## Подключение к ChatGPT Desktop

[Официальная инструкция MCP](https://learn.chatgpt.com/docs/extend/mcp):
Settings → MCP servers → Add server, транспорт STDIO.

- Command: `/absolute/path/tbank-mcp/.venv/bin/python`
- Arguments: `/absolute/path/tbank-mcp/server.py`
- Environment: `TBANK_SESSION`, только если выбран нестандартный путь.

Пути должны существовать на машине, где исполняется MCP. Пример записи в
`~/.codex/config.toml` для общего Codex host Desktop:

```toml
[mcp_servers.tbank_personal]
command = "/absolute/path/tbank-mcp/.venv/bin/python"
args = ["/absolute/path/tbank-mcp/server.py"]
```

После добавления нажмите Restart. Рабочая директория не важна. Токен
T-Invest API не нужен. Настройки Desktop этот проект автоматически не меняет.

## Проверки

```bash
.venv/bin/python -m unittest discover -s tests -v
```

Синтетические ответы, без реальных банковских данных: разрешённые адреса и методы,
редиректы, прокси, TLS, точность денег, ошибки, права файла сессии, шаги входа,
периоды и страницы истории, настоящий stdio handshake при запрещённых сетевых
соединениях. Это не заменяет проверку входа и чтения на живом аккаунте.