Ю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> })

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

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

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

1. Заведите тестовый магазин в личном кабинете ЮKassa и

используйте его YOOKASSA_SHOP_ID / YOOKASSA_SECRET_KEY.

1. Убедитесь, что вы в тестовом режиме — вызовите `get_shop_info` и проверьте "test": true —

до переключения на боевой магазин.

1. В боевом магазине create_payment, create_refund, create_payout, create_recurring_payment,

save_payment_method и capture_payment двигают реальные деньги и необратимы. Эти инструменты помечены как разрушающие, чтобы MCP-клиенты спрашивали подтверждение перед запуском.

1. HTTP-транспорт по умолчанию отказывает без авторизации и слушает localhost — перед любым удалённым

развёртыванием прочитайте SECURITY.md.

Инструменты (20)

Платежи (9)

Возвраты (3)

Чеки (2)

Выплаты (2)

⚠️ Выплаты — отдельно подключаемый продукт ЮKassa со своими реквизитами шлюза (YOOKASSA_PAYOUT_AGENT_ID + YOOKASSA_PAYOUT_SECRET_KEY), это не платёжный ключ магазина. Передача сырого номера карты требует сертификата PCI DSS — без него собирайте реквизиты получателя через виджет выплат и передавайте payout_token. Выплаты асинхронные (опрашивайте get_payout).

Вебхуки (3)

Аккаунт (1)

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

Создай платёж на 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

Лицензия

MIT

Часть WWmcp · Telegram: @vhodvai