mcp-server-tochka-bank

MCP-сервер, CLI-утилита и библиотека Pydantic-моделей для API банка Точка.

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

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

Оглавление

• Возможности
• MCP-сервер
  • Установка
  • Подключение к Claude Code
  • Подключение к Claude Desktop
  • Подключение через --mcp-config
  • Примеры
• CLI-утилита
  • Установка
  • Использование
  • Примеры команд
• 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. Войдите в интернет-банк Точка
2. Перейдите в Настройки → Интеграции и API
3. Нажмите «Создать токен» (JWT)
4. Выберите разрешения:
   • ReadAccountsBasic, ReadAccountsDetail — информация о счетах
   • ReadBalances — баланс
   • ReadStatements — выписки
   • ReadCustomerData — данные клиентов
   • CreatePaymentForSign, ReadPaymentData — платежи
   • ManageInvoiceData — счета и закрывающие документы
   • ReadAcquiringData, MakeAcquiringOperation — эквайринг и подписки
5. Скопируйте сгенерированный токен

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

Подключение к Claude Code

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

Требуется uv — если не установлен:

curl -LsSf https://astral.sh/uv/install.sh | sh

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

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

pip install mcp-server-tochka-bank

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

Для удаления:

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:

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

Через pip (после pip install mcp-server-tochka-bank):

{
  "mcpServers": {
    "tochka-bank": {
      "command": "python",
      "args": ["-m", "mcp_server_tochka_bank"],
      "env": {
        "TOCHKA_TOKEN": "ваш_токен"
      }
    }
  }
}

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

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

Из JSON-строки:

claude --mcp-config '{"tochka-bank":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-tochka-bank"]}}'

Из файла:

claude --mcp-config ~/mcp-servers.json

Пример ~/mcp-servers.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)

pip install mcp-server-tochka-bank

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

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

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

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

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

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

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

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

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

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

# Баланс
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.

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

pip install mcp-server-tochka-bank

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

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

---

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

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

Разработка

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

Лицензия

MIT