yookassa-mcp

ЮKassa MCP — приём платежей и чеки 54-ФЗ из Claude и других AI-агентов

Если вы искали, как подключить ЮKassa к нейросети, проводить платежи и возвраты прямо в диалоге или автоматизировать фискальные чеки по 54-ФЗ без написания кода — это оно. 20 инструментов закрывают весь оборот денег: платежи, возвраты, чеки, выплаты, вебхуки, рекуррентные списания, СБП и сплиты маркетплейса. Ставится в Claude Desktop, Cursor или любой MCP-клиент одной строкой конфига.

Часть серии WWmcp от @theYahia.

Быстрый старт

Claude Desktop

{
  "mcpServers": {
    "yookassa": {
      "command": "npx",
      "args": ["-y", "@theyahia/yookassa-mcp"],
      "env": {
        "YOOKASSA_SHOP_ID": "your-shop-id",
        "YOOKASSA_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Claude Code

claude mcp add yookassa -e YOOKASSA_SHOP_ID=your-id -e YOOKASSA_SECRET_KEY=your-key -- npx -y @theyahia/yookassa-mcp

VS Code / Cursor

{
  "servers": {
    "yookassa": {
      "command": "npx",
      "args": ["-y", "@theyahia/yookassa-mcp"],
      "env": {
        "YOOKASSA_SHOP_ID": "your-shop-id",
        "YOOKASSA_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "yookassa": {
      "command": "npx",
      "args": ["-y", "@theyahia/yookassa-mcp"],
      "env": {
        "YOOKASSA_SHOP_ID": "your-shop-id",
        "YOOKASSA_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Streamable HTTP (удалённый сервер / Docker)

⚠️ HTTP-транспорт открывает инструменты, которые двигают деньги. Он требует Bearer-токен, по умолчанию слушает 127.0.0.1 и проверяет Host/Origin (защита от DNS-rebinding). Никогда не выставляйте его напрямую в интернет — только за обратным прокси с аутентификацией или mTLS. См. SECURITY.md.

MCP_AUTH_TOKEN="$(openssl rand -hex 32)" HTTP_PORT=3000 npx -y @theyahia/yookassa-mcp --http

Затем обращайтесь к /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; секреты, заголовок авторизации и тела запросов не логируются

Тестовый режим и безопасность

Сервер выполняет реальные денежные операции. На время разработки:

1. Заведите тестовый магазин в личном кабинете ЮKassa и используйте его YOOKASSA_SHOP_ID / YOOKASSA_SECRET_KEY.
2. Убедитесь, что вы в тестовом режиме — вызовите get_shop_info и проверьте "test": true — до переключения на боевой магазин.
3. В боевом магазине create_payment, create_refund, create_payout, create_recurring_payment, save_payment_method и capture_payment двигают реальные деньги и необратимы. Эти инструменты помечены как разрушающие, чтобы MCP-клиенты спрашивали подтверждение перед запуском.
4. 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 нет)

Демо-промпты

Создай платёж на 5000 рублей по заказу #123 со способом оплаты СБП

Настрой рекуррентную подписку: привяжи карту списанием 1 рубля, потом списывай 999 рублей ежемесячно по сохранённому способу

Покажи все успешные платежи за последние 7 дней и сделай возврат 2500 рублей по платежу pay_xxx

Архитектура

• Авторизация: HTTP Basic Auth (YOOKASSA_SHOP_ID:YOOKASSA_SECRET_KEY)
• Базовый URL: https://api.yookassa.ru/v3/
• Idempotence-Key: один стабильный UUID v4 на каждый логический POST/DELETE-запрос, сохраняется при повторах (повторный запрос дедуплицируется на стороне ЮKassa, двойного списания не будет). Вызывающая сторона может передать свой ключ.
• Таймаут: 35 секунд (больше, чем окно ответа ЮKassa ~30 с, чтобы медленная, но успешная операция не обрывалась на клиенте)
• Повторы: 3 попытки на 429/5xx/таймаут с экспоненциальной задержкой (1 с, 2 с, 4 с); повторы переиспользуют тот же Idempotence-Key и безопасно дедуплицируются
• Транспорт: stdio (по умолчанию) или Streamable HTTP (--http / HTTP_PORT)

Часть серии WWmcp

MCP	Статус	Описание
@metarebalance/dadata-mcp	готов	Адреса, компании, банки, телефоны
@theyahia/cbr-mcp	готов	Курсы валют, ключевая ставка
@theyahia/yookassa-mcp	готов	Платежи, возвраты, чеки, выплаты, вебхуки
@theyahia/cloudpayments-mcp	готов	Платежи, подписки, заказы
...		46 серверов — полный список

Лицензия

MIT

---

Часть WWmcp · Telegram: @vhodvai