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

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

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

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

Claude Desktop

config.json

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

Claude Code

Terminal

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

VS Code / Cursor

config.json

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

Windsurf

config.json

{
  "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.

bash

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

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

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

Заведите тестовый магазин в личном кабинете Ю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

Архитектура

Авторизация: 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