Metadata-Version: 2.4
Name: mcp-server-tochka-bank
Version: 0.3.2
Summary: MCP server for Tochka Bank API — balance, payments, invoices, UPD
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.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'
Description-Content-Type: text/markdown

<!-- 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_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` — информация о счетах
   - `ReadBalances` — баланс
   - `ReadStatements` — выписки
   - `CreatePaymentForSign` — создание платежей
   - `ManageInvoiceData` — счета и закрывающие документы
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`.

## Примеры

- «покажи баланс» → `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`

## Лицензия

MIT
