Metadata-Version: 2.4
Name: mcp-server-tochka-bank
Version: 0.6.2
Summary: MCP server for Tochka Bank API — balance, payments, invoices, UPD, acquiring, subscriptions, consents
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.28
Provides-Extra: test
Requires-Dist: anyio>=4.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Requires-Dist: ruff>=0.4; extra == 'test'
Description-Content-Type: text/markdown

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

# mcp-server-tochka-bank

[![Version](https://img.shields.io/badge/version-0.6.2-blue)](https://github.com/dontsovcmc/mcp-server-tochka-bank)

MCP-сервер, CLI-утилита и библиотека Pydantic-моделей для [API банка Точка](https://developers.tochka.com/docs/tochka-api/).

- **MCP-сервер** — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами
- **CLI-утилита** — работа с API из терминала, скрипты и автоматизация
- **Pydantic-модели** — типизированные модели API для использования в своих Python-программах

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

## Оглавление

- [Возможности](#возможности)
- [MCP-сервер](#mcp-сервер)
  - [Установка](#установка)
  - [Подключение к Claude Code](#подключение-к-claude-code)
  - [Подключение к Claude Desktop](#подключение-к-claude-desktop)
  - [Подключение через --mcp-config](#подключение-через---mcp-config)
  - [Примеры](#примеры-mcp)
- [CLI-утилита](#cli-утилита)
  - [Установка](#установка-cli)
  - [Использование](#использование-cli)
  - [Примеры команд](#примеры-команд)
- [Pydantic-модели](#pydantic-модели)
  - [Установка](#установка-библиотеки)
  - [Использование в своих программах](#использование-в-своих-программах)
- [Переменные окружения](#переменные-окружения)
- [Разработка](#разработка)
- [Лицензия](#лицензия)

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

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

### Счета и документы (дополнительно)
| Инструмент | CLI | Описание |
|------------|-----|----------|
| `tochka_account_detail` | `account-detail` | Детали банковского счёта |
| `tochka_all_balances` | `all-balances` | Балансы всех счетов |
| `tochka_statements_list` | `statements-list` | Список последних выписок |
| `tochka_card_transactions` | `card-transactions` | Авторизованные карточные транзакции |
| `tochka_customers` | `customers` | Список клиентов (организаций) |
| `tochka_customer` | `customer` | Детали клиента |
| `tochka_delete_invoice` | `delete-invoice` | Удалить счёт |
| `tochka_send_invoice_email` | `send-invoice-email` | Отправить счёт на email |
| `tochka_delete_closing_document` | `delete-closing-document` | Удалить закрывающий документ |
| `tochka_send_closing_document_email` | `send-closing-document-email` | Отправить закрывающий документ на email |
| `tochka_download_closing_document` | `download-closing-document` | Скачать PDF закрывающего документа |
| `tochka_payments_for_sign` | `payments-for-sign` | Список платежей на подпись |

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

### Подписки (рекуррентные платежи)
| Инструмент | CLI | Описание |
|------------|-----|----------|
| `tochka_subscription_create` | `subscription-create` | Создать подписку |
| `tochka_subscriptions` | `subscriptions` | Список подписок |
| `tochka_subscription_charge` | `subscription-charge` | Списание по подписке |
| `tochka_subscription_status` | `subscription-status` | Статус подписки |
| `tochka_subscription_status_set` | `subscription-status-set` | Установить статус подписки |
| `tochka_subscription_with_receipt` | `subscription-with-receipt` | Создать подписку с фискальным чеком |

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

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

| Инструмент | CLI | Описание |
|------------|-----|----------|
| `tochka_track_invoice` | — | Добавить счёт в отслеживание оплаты |
| `tochka_untrack_invoice` | — | Убрать счёт из отслеживания |
| `tochka_pending_invoices` | `pending-invoices` | Список счетов, ожидающих оплаты |
| `tochka_check_invoices` | `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 покажет неоплаченные и запустит периодическую проверку.

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

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

---

## MCP-сервер

### Установка

#### Шаг 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

**Способ 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": "ваш_токен"
      }
    }
  }
}
```

### Подключение через --mcp-config

Подключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном `.env.mcp` файле, а не в конфиге Claude.

Из JSON-строки:
```bash
claude --mcp-config '{"tochka-bank":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-tochka-bank"]}}'
```

Из файла:
```bash
claude --mcp-config ~/mcp-servers.json
```

Пример `~/mcp-servers.json`:
```json
{
  "tochka-bank": {
    "command": "bash",
    "args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-tochka-bank"]
  }
}
```

Пример `~/.env.mcp`:
```
TOCHKA_TOKEN=ваш_токен
```

#### Шаг 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)

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

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

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

Или через файл:

```bash
mcp-server-tochka-bank --env /path/to/.env balance
```

Формат файла — `KEY=VALUE`, по одной переменной на строку, `#`-комментарии.

### Использование (CLI)

Без аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.

```bash
# Версия
mcp-server-tochka-bank --version

# Справка
mcp-server-tochka-bank --help
mcp-server-tochka-bank <command> --help
```

### Примеры команд

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

---

## Pydantic-модели

Пакет содержит типизированные Pydantic-модели всех объектов API. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.

### Установка (библиотеки)

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

### Использование в своих программах

```python
from mcp_server_tochka_bank.models import Balance, Account, Transaction

# Валидация данных из API
data = {"type": "ClosingAvailable", "accountId": "40702810100000000001/044525000"}
balance = Balance.model_validate(data)
print(balance.type)  # type-safe доступ к полям

# Создание объекта
account = Account(accountId="40702810100000000001/044525000", customerCode="100000001")
print(account.model_dump_json())
```

Все модели используют `extra="allow"` для forward compatibility — неизвестные поля API не вызывают ошибок.

Полный список моделей: [`models.py`](src/mcp_server_tochka_bank/models.py)

---

## Переменные окружения

| Переменная | Обязательная | По умолчанию | Описание |
|------------|:------------:|:------------:|----------|
| `TOCHKA_TOKEN` | да | — | JWT-токен API банка Точка |
| `TOCHKA_TIMEOUT` | нет | `30` | Таймаут HTTP-запросов к API (секунды) |
| `TOCHKA_FILE_TIMEOUT` | нет | `60` | Таймаут скачивания файлов (секунды) |

## Разработка

```bash
pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v
```

## Лицензия

MIT
