<!-- mcp-name: io.github.dontsovcmc/tochka-bank -->

# mcp-server-tochka-bank

MCP-сервер для работы с [API банка Точка](https://developers.tochka.com/docs/tochka-api/) через Claude Code, Claude Desktop и другие MCP-совместимые клиенты.

Все данные остаются на вашем компьютере — токен никуда не передаётся.

## Возможности

### Банковские операции
| Инструмент | Описание |
|------------|----------|
| `tochka_balance` | Баланс счёта |
| `tochka_payment` | Создать исходящий платёж (я плачу кому-то), получить ссылку на подпись |
| `tochka_invoice` | Выставить счёт покупателю (мне платят) |
| `tochka_download_invoice` | Скачать PDF счёта |
| `tochka_upd` | Создать УПД (универсальный передаточный документ), получить ссылку на подпись |
| `tochka_search` | Поиск операций по ИНН или названию контрагента (возвращает полные реквизиты: БИК, счёт, корр.счёт) |
| `tochka_incoming` | Входящие поступления за месяц, сгруппированные по ИНН отправителя (для налоговых отчётов АУСН) |

### Счета и документы (дополнительно)
| Инструмент | Описание |
|------------|----------|
| `tochka_account_detail` | Детали банковского счёта |
| `tochka_all_balances` | Балансы всех счетов |
| `tochka_statements_list` | Список последних выписок |
| `tochka_card_transactions` | Авторизованные карточные транзакции |
| `tochka_customers` | Список клиентов (организаций) |
| `tochka_customer` | Детали клиента |
| `tochka_delete_invoice` | Удалить счёт |
| `tochka_send_invoice_email` | Отправить счёт на email |
| `tochka_delete_closing_document` | Удалить закрывающий документ |
| `tochka_send_closing_document_email` | Отправить закрывающий документ на email |
| `tochka_download_closing_document` | Скачать PDF закрывающего документа |
| `tochka_payments_for_sign` | Список платежей на подпись |

### Эквайринг (платёжные ссылки)
| Инструмент | Описание |
|------------|----------|
| `tochka_acquiring_payments` | Список операций эквайринга |
| `tochka_acquiring_payment_create` | Создать платёжную ссылку |
| `tochka_acquiring_payment` | Детали операции эквайринга |
| `tochka_acquiring_payment_capture` | Списать средства (двухстадийный платёж) |
| `tochka_acquiring_payment_refund` | Возврат платежа |
| `tochka_acquiring_payment_with_receipt` | Создать платёж с фискальным чеком |
| `tochka_acquiring_registry` | Реестр платежей эквайринга |
| `tochka_acquiring_retailers` | Список торговых точек |

### П��дписки (рекуррентные платежи)
| Инструмент | Описание |
|------------|----------|
| `tochka_subscription_create` | Создать подписку |
| `tochka_subscriptions` | Список подписок |
| `tochka_subscription_charge` | Списание по подписке |
| `tochka_subscription_status` | Статус подписки |
| `tochka_subscription_status_set` | Установить статус подписки |
| `tochka_subscription_with_receipt` | Создать подписку с фискальным чеком |

### Разрешения API (Consents)
| Инструмент | Описание |
|------------|----------|
| `tochka_consents` | Список разрешений |
| `tochka_consent_create` | Создать разрешение |
| `tochka_consent` | Детали разрешения |
| `tochka_consent_children` | Дочерние разрешения |

### Отслеживание оплаты счетов

| Инструмент | Описание |
|------------|----------|
| `tochka_track_invoice` | Добавить счёт в отслеживание оплаты |
| `tochka_untrack_invoice` | Убрать счёт из отслеживания |
| `tochka_pending_invoices` | Список счетов, ожидающих оплаты |
| `tochka_check_invoices` | Проверить все ожидающие счета, оплаченные удаляются автоматически |

Данные хранятся в `~/.config/mcp-server-tochka-bank/pending_invoices.json`.

Два способа отслеживания в зависимости от того, как был создан счёт:

**Счёт создан через MCP-сервер** (`tochka_invoice`) — данные сохраняются автоматически. Проверка оплаты через `payment-status` API Точки. Признак оплаты: статус счёта в API Точки изменился на "оплачен".

**Счёт создан вручную** (в интернет-банке) — нужно указать ИНН плательщика и сумму при добавлении в трекер (`tochka_track_invoice`). Проверка оплаты через банковскую выписку. Признаки оплаты (все условия одновременно):
- Входящий платёж (Credit)
- ИНН плательщика совпадает с `buyer_inn`
- Дата платежа >= дата создания записи в трекере
- Разница суммы платежа и суммы счёта не более 1 рубля

После выставления счёта через MCP он автоматически попадает в отслеживание. При старте сессии Claude покажет неоплаченные и запустит периодическую проверку.

### Локальный справочник товаров
| Инструмент | Описание |
|------------|----------|
| `goods_list` | Список всех товаров |
| `goods_add` | Добавить товар (название, единица измерения, цена) |
| `goods_remove` | Удалить товар по названию |

Товары хранятся локально в `~/.config/mcp-server-tochka-bank/goods.json`.

## Настройка

### Шаг 1. Получить JWT-токен в банке Точка

1. Войдите в [интернет-банк Точка](https://i.tochka.com)
2. Перейдите в **Настройки** → **Интеграции и API**
3. Нажмите **«Создать токен»** (JWT)
4. Выберите разрешения:
   - `ReadAccountsBasic`, `ReadAccountsDetail` — информация о счетах
   - `ReadBalances` — баланс
   - `ReadStatements` — выписки
   - `ReadCustomerData` — данные клиентов
   - `CreatePaymentForSign`, `ReadPaymentData` — платежи
   - `ManageInvoiceData` — счета и закрывающие документы
   - `ReadAcquiringData`, `MakeAcquiringOperation` — эквайринг и подписки
5. Скопируйте сгенерированный токен

### Шаг 2. Подключить MCP-сервер

#### Claude Code (CLI в терминале)

**Способ 1: через uvx** (не требует установки пакета)

> Требуется [uv](https://docs.astral.sh/uv/) — если не установлен:
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```

```bash
claude mcp add tochka-bank \
  -e TOCHKA_TOKEN=ваш_токен \
  -- uvx mcp-server-tochka-bank
```

**Способ 2: через pip**

```bash
pip install mcp-server-tochka-bank

claude mcp add tochka-bank \
  -e TOCHKA_TOKEN=ваш_токен \
  -- python -m mcp_server_tochka_bank
```

Для удаления:
```bash
claude mcp remove tochka-bank
```

#### Claude Desktop (десктопное приложение)

Добавьте в конфигурационный файл:

| Клиент | ОС | Путь к файлу |
|--------|----|-------------|
| Claude Code | все | `~/.claude/settings.json` (секция `mcpServers`) |
| Claude Desktop | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop | Linux | `~/.config/Claude/claude_desktop_config.json` |

**Через uvx:**
```json
{
  "mcpServers": {
    "tochka-bank": {
      "command": "uvx",
      "args": ["mcp-server-tochka-bank"],
      "env": {
        "TOCHKA_TOKEN": "ваш_токен"
      }
    }
  }
}
```

**Через pip** (после `pip install mcp-server-tochka-bank`):
```json
{
  "mcpServers": {
    "tochka-bank": {
      "command": "python",
      "args": ["-m", "mcp_server_tochka_bank"],
      "env": {
        "TOCHKA_TOKEN": "ваш_токен"
      }
    }
  }
}
```

Для удаления — удалите блок `"tochka-bank"` из файла.

Токен хранится только на вашем компьютере и передаётся серверу через переменную окружения.

### Шаг 3. Проверить

Попросите Claude: *«покажи баланс в банке Точка»* — он вызовет `tochka_balance`.

## Примеры (MCP)

- «покажи баланс» → `tochka_balance`
- «выстави счёт ООО Рога и Копыта на 15 000 ₽» → `tochka_invoice`
- «создай УПД к этому счёту» → `tochka_upd`
- «оплати Попову 5000» → `tochka_search` (найти реквизиты) → `tochka_payment` (создать платёж) → ссылка на подпись
- «оплати по реквизитам ...» → `tochka_payment`
- «найди все операции с ИНН 7700000000» → `tochka_search`
- «добавь товар: Виджет, шт., 500.00» → `goods_add`
- «отслеживай оплату счёта №140» → `tochka_track_invoice`
- «какие счета не оплачены?» → `tochka_pending_invoices`
- «проверь оплату» → `tochka_check_invoices`

## CLI-режим

Пакет можно использовать как CLI-инструмент в терминале. Без аргументов запускается MCP-сервер, с командой — CLI.

### Требования

Переменная окружения `TOCHKA_TOKEN` должна быть установлена:

```bash
export TOCHKA_TOKEN=ваш_токен
```

### Команды

```bash
# Баланс
mcp-server-tochka-bank balance
mcp-server-tochka-bank all-balances
mcp-server-tochka-bank account-detail --account-id 40702810100000000001/044525000

# Поиск операций по ИНН или названию
mcp-server-tochka-bank search 7700000000
mcp-server-tochka-bank search робокасса --days 60

# Входящие поступления за месяц (для налоговых отчётов)
mcp-server-tochka-bank incoming --month 3 --year 2026
mcp-server-tochka-bank incoming --month 3 --year 2026 --inn 3532015985

# Выписки и транзакции
mcp-server-tochka-bank statements-list --limit 10
mcp-server-tochka-bank card-transactions

# Клиенты
mcp-server-tochka-bank customers
mcp-server-tochka-bank customer 100000001

# Счета и документы
mcp-server-tochka-bank delete-invoice <document_id>
mcp-server-tochka-bank send-invoice-email <document_id> buyer@example.com
mcp-server-tochka-bank download-closing-document <document_id> /tmp/upd.pdf
mcp-server-tochka-bank payments-for-sign

# Эквайринг
mcp-server-tochka-bank acquiring-payments --page 1
mcp-server-tochka-bank acquiring-payment <operation_id>
mcp-server-tochka-bank acquiring-retailers

# Подписки
mcp-server-tochka-bank subscriptions
mcp-server-tochka-bank subscription-status <operation_id>

# Разрешения
mcp-server-tochka-bank consents
mcp-server-tochka-bank consent <consent_id>

# Справочник товаров
mcp-server-tochka-bank goods list
mcp-server-tochka-bank goods add --name "Виджет" --unit "шт." --price "500.00"
mcp-server-tochka-bank goods remove --name "Виджет"

# Отслеживание оплаты
mcp-server-tochka-bank pending-invoices
mcp-server-tochka-bank check-invoices --days 30
```

Все команды выводят результат в JSON.

## Лицензия

MIT