MCP server for YooKassa payment API — payments, refunds, receipts (54-FZ). 10 tools. First MCP for
MCP server for YooKassa payment API providing payments, refunds, and receipts under 54-FZ. It exposes 10 tools for integrating YooKassa into Claude and other AI agents via Model Context Protocol. The published package is @theyahia/yookassa-mcp and is intended to be used from an MCP client.
🛠️ Key Features
YooKassa payments
Refunds
Fiscal receipts for 54-FZ
🚀 Use Cases
Handle payment flows directly from an AI-agent dialogue
Automate refund and receipt-related steps in compliant (54-FZ) workflows
⚡ Developer Benefits
Uses MCP to connect YooKassa functionality to MCP clients
Includes a configuration-based setup for Claude Desktop, Cursor, or other MCP clients
⚠️ Limitations
Readme excerpt provided is partial and describes “10 tools” generally; further capabilities beyond payments, refunds, and receipts are not fully enumerated in the source excerpt.
ЮKassa MCP — приём платежей и чеки 54-ФЗ из Claude и других AI-агентов
Если вы искали, как подключить ЮKassa к нейросети, проводить платежи и возвраты прямо в диалоге или автоматизировать фискальные чеки по 54-ФЗ без написания кода — это оно. 20 инструментов закрывают весь оборот денег: платежи, возвраты, чеки, выплаты, вебхуки, рекуррентные списания, СБП и сплиты маркетплейса. Ставится в Claude Desktop, Cursor или любой MCP-клиент одной строкой конфига.
⚠️ HTTP-транспорт открывает инструменты, которые двигают деньги. Он требует Bearer-токен,
по умолчанию слушает 127.0.0.1 и проверяет Host/Origin (защита от DNS-rebinding).
Никогда не выставляйте его напрямую в интернет — только за обратным прокси с аутентификацией или mTLS.
См. SECURITY.md.
Затем обращайтесь к /mcp с заголовком Authorization: Bearer <MCP_AUTH_TOKEN>.
Эндпоинты:
POST /mcp — транспорт MCP Streamable HTTP (нужен Bearer-токен; stateless — только POST)
GET /health — проверка состояния без авторизации ({ "status": "ok", "tools": <count> })
Переменные окружения
Переменная
Обяз.
Описание
YOOKASSA_SHOP_ID
да
ID магазина (Настройки → Магазин)
YOOKASSA_SECRET_KEY
да
Секретный ключ (Интеграция → Ключи API)
YOOKASSA_PAYOUT_AGENT_ID
для выплат
ID шлюза (agentId) продукта «Выплаты» (Настройки → Выплаты)
YOOKASSA_PAYOUT_SECRET_KEY
для выплат
Секретный ключ шлюза выплат
HTTP_PORT
нет
Порт HTTP-транспорта (по умолчанию 3000); включает режим --http
MCP_AUTH_TOKEN
только HTTP
Обязателен в HTTP-режиме. Bearer-токен, который клиенты шлют на /mcp
HTTP_HOST
нет
Адрес привязки в HTTP-режиме (по умолчанию 127.0.0.1; 0.0.0.0 — только за прокси)
MCP_ALLOWED_HOSTS
нет
Список разрешённых Host через запятую (по умолчанию 127.0.0.1:<port>,localhost:<port>)
MCP_ALLOWED_ORIGINS
нет
Список разрешённых браузерных Origin (CORS) через запятую (по умолчанию пусто — браузерные origin отклоняются)
YOOKASSA_DEBUG
нет
1 — трассировать каждый запрос (метод/путь/статус/задержка/ключ идемпотентности) в stderr; секреты, заголовок авторизации и тела запросов не логируются
Тестовый режим и безопасность
Сервер выполняет реальные денежные операции. На время разработки:
Заведите тестовый магазин в личном кабинете ЮKassa и
используйте его YOOKASSA_SHOP_ID / YOOKASSA_SECRET_KEY.
Убедитесь, что вы в тестовом режиме — вызовите get_shop_info и проверьте "test": true —
до переключения на боевой магазин.
В боевом магазине create_payment, create_refund, create_payout, create_recurring_payment,
save_payment_method и capture_payment двигают реальные деньги и необратимы. Эти инструменты
помечены как разрушающие, чтобы MCP-клиенты спрашивали подтверждение перед запуском.
HTTP-транспорт по умолчанию отказывает без авторизации и слушает localhost — перед любым удалённым
развёртыванием прочитайте SECURITY.md.
Инструменты (20)
Платежи (9)
Инструмент
Описание
create_payment
Создать платёж с суммой, описанием и способом оплаты. Возвращает ссылку на оплату. Поддерживает чеки и метаданные
get_payment
Данные платежа по ID — статус, сумма, ссылка подтверждения, метаданные
capture_payment
Подтвердить двухстадийный платёж (списать удержанные средства). Частичное списание поддерживается
cancel_payment
Отменить платёж (в статусе pending или waiting_for_capture)
list_payments
Список платежей с фильтрами по статусу, периоду и пагинацией
save_payment_method
Сохранить способ оплаты для рекуррентных списаний (привязка карты)
create_recurring_payment
Списать по сохранённому способу оплаты (без участия пользователя)
create_sbp_payment
Создать платёж через СБП (Система быстрых платежей)
create_split_payment
Сплит-платёж для маркетплейсов — распределение денег между партнёрами
Возвраты (3)
Инструмент
Описание
create_refund
Полный или частичный возврат по ID платежа
get_refund
Данные возврата по ID
list_refunds
Список возвратов с необязательным фильтром по платежу
Чеки (2)
Инструмент
Описание
create_receipt
Фискальный чек (54-ФЗ) — позиции, коды НДС, контакты покупателя
list_receipts
Список чеков по ID платежа или возврата
Выплаты (2)
⚠️ Выплаты — отдельно подключаемый продукт ЮKassa со своими реквизитами шлюза
(YOOKASSA_PAYOUT_AGENT_ID + YOOKASSA_PAYOUT_SECRET_KEY), это не платёжный ключ магазина.
Передача сырого номера карты требует сертификата PCI DSS — без него собирайте реквизиты получателя
через виджет выплат и передавайте payout_token. Выплаты асинхронные (опрашивайте get_payout).
Инструмент
Описание
create_payout
Выплата на банковскую карту, кошелёк ЮMoney или через СБП, либо по payout_token
get_payout
Статус и детали выплаты по ID
Вебхуки (3)
Инструмент
Описание
create_webhook
Зарегистрировать URL вебхука для событий (payment.succeeded, refund.succeeded и т. д.)
list_webhooks
Список всех зарегистрированных вебхуков
delete_webhook
Удалить вебхук по ID
Аккаунт (1)
Инструмент
Описание
get_shop_info
Информация о магазине — ID, статус, тестовый режим, фискализация (эндпоинта баланса в ЮKassa нет)
Демо-промпты
code
Создай платёж на 5000 рублей по заказу #123 со способом оплаты СБП
code
Настрой рекуррентную подписку: привяжи карту списанием 1 рубля, потом списывай 999 рублей ежемесячно по сохранённому способу
code
Покажи все успешные платежи за последние 7 дней и сделай возврат 2500 рублей по платежу pay_xxx
Idempotence-Key: один стабильный UUID v4 на каждый логический POST/DELETE-запрос, сохраняется при повторах (повторный запрос дедуплицируется на стороне ЮKassa, двойного списания не будет). Вызывающая сторона может передать свой ключ.
Таймаут: 35 секунд (больше, чем окно ответа ЮKassa ~30 с, чтобы медленная, но успешная операция не обрывалась на клиенте)
Повторы: 3 попытки на 429/5xx/таймаут с экспоненциальной задержкой (1 с, 2 с, 4 с); повторы переиспользуют тот же Idempotence-Key и безопасно дедуплицируются
Транспорт: stdio (по умолчанию) или Streamable HTTP (--http / HTTP_PORT)
