{
  "markdown": "# ЮKassa MCP — приём платежей и чеки 54-ФЗ из Claude и других AI-агентов\n\nЕсли вы искали, как подключить ЮKassa к нейросети, проводить платежи и возвраты прямо в диалоге или автоматизировать фискальные чеки по 54-ФЗ без написания кода — это оно. 20 инструментов закрывают весь оборот денег: платежи, возвраты, чеки, выплаты, вебхуки, рекуррентные списания, СБП и сплиты маркетплейса. Ставится в Claude Desktop, Cursor или любой MCP-клиент одной строкой конфига.\n\n[![npm](https://img.shields.io/npm/v/@theyahia/yookassa-mcp)](https://www.npmjs.com/package/@theyahia/yookassa-mcp)\n[![CI](https://github.com/theYahia/yookassa-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/theYahia/yookassa-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![smithery badge](https://smithery.ai/badge/@theyahia/yookassa-mcp)](https://smithery.ai/server/@theyahia/yookassa-mcp)\n\nЧасть серии [WWmcp](https://github.com/theYahia/WWmcp) от [@theYahia](https://github.com/theYahia).\n\n## Быстрый старт\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"yookassa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@theyahia/yookassa-mcp\"],\n      \"env\": {\n        \"YOOKASSA_SHOP_ID\": \"your-shop-id\",\n        \"YOOKASSA_SECRET_KEY\": \"your-secret-key\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add yookassa -e YOOKASSA_SHOP_ID=your-id -e YOOKASSA_SECRET_KEY=your-key -- npx -y @theyahia/yookassa-mcp\n```\n\n### VS Code / Cursor\n\n```json\n{\n  \"servers\": {\n    \"yookassa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@theyahia/yookassa-mcp\"],\n      \"env\": {\n        \"YOOKASSA_SHOP_ID\": \"your-shop-id\",\n        \"YOOKASSA_SECRET_KEY\": \"your-secret-key\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\n```json\n{\n  \"mcpServers\": {\n    \"yookassa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@theyahia/yookassa-mcp\"],\n      \"env\": {\n        \"YOOKASSA_SHOP_ID\": \"your-shop-id\",\n        \"YOOKASSA_SECRET_KEY\": \"your-secret-key\"\n      }\n    }\n  }\n}\n```\n\n### Streamable HTTP (удалённый сервер / Docker)\n\n> ⚠️ **HTTP-транспорт открывает инструменты, которые двигают деньги.** Он требует Bearer-токен,\n> по умолчанию слушает `127.0.0.1` и проверяет `Host`/`Origin` (защита от DNS-rebinding).\n> Никогда не выставляйте его напрямую в интернет — только за обратным прокси с аутентификацией или mTLS.\n> См. [SECURITY.md](SECURITY.md).\n\n```bash\nMCP_AUTH_TOKEN=\"$(openssl rand -hex 32)\" HTTP_PORT=3000 npx -y @theyahia/yookassa-mcp --http\n```\n\nЗатем обращайтесь к `/mcp` с заголовком `Authorization: Bearer <MCP_AUTH_TOKEN>`.\n\nЭндпоинты:\n- `POST /mcp` — транспорт MCP Streamable HTTP (нужен Bearer-токен; stateless — только POST)\n- `GET /health` — проверка состояния без авторизации (`{ \"status\": \"ok\", \"tools\": <count> }`)\n\n## Переменные окружения\n\n| Переменная | Обяз. | Описание |\n|----------|:--------:|-------------|\n| `YOOKASSA_SHOP_ID` | да | ID магазина (Настройки → Магазин) |\n| `YOOKASSA_SECRET_KEY` | да | Секретный ключ (Интеграция → Ключи API) |\n| `YOOKASSA_PAYOUT_AGENT_ID` | для выплат | ID шлюза (agentId) продукта «Выплаты» (Настройки → Выплаты) |\n| `YOOKASSA_PAYOUT_SECRET_KEY` | для выплат | Секретный ключ шлюза выплат |\n| `HTTP_PORT` | нет | Порт HTTP-транспорта (по умолчанию 3000); включает режим `--http` |\n| `MCP_AUTH_TOKEN` | только HTTP | **Обязателен в HTTP-режиме.** Bearer-токен, который клиенты шлют на `/mcp` |\n| `HTTP_HOST` | нет | Адрес привязки в HTTP-режиме (по умолчанию `127.0.0.1`; `0.0.0.0` — только за прокси) |\n| `MCP_ALLOWED_HOSTS` | нет | Список разрешённых `Host` через запятую (по умолчанию `127.0.0.1:<port>,localhost:<port>`) |\n| `MCP_ALLOWED_ORIGINS` | нет | Список разрешённых браузерных `Origin` (CORS) через запятую (по умолчанию пусто — браузерные origin отклоняются) |\n| `YOOKASSA_DEBUG` | нет | `1` — трассировать каждый запрос (метод/путь/статус/задержка/ключ идемпотентности) в stderr; секреты, заголовок авторизации и тела запросов не логируются |\n\n## Тестовый режим и безопасность\n\nСервер выполняет **реальные денежные операции**. На время разработки:\n\n1. Заведите **тестовый магазин** в [личном кабинете ЮKassa](https://yookassa.ru/my/shop-settings) и\n   используйте его `YOOKASSA_SHOP_ID` / `YOOKASSA_SECRET_KEY`.\n2. Убедитесь, что вы в тестовом режиме — вызовите **`get_shop_info`** и проверьте `\"test\": true` —\n   **до** переключения на боевой магазин.\n3. В **боевом** магазине `create_payment`, `create_refund`, `create_payout`, `create_recurring_payment`,\n   `save_payment_method` и `capture_payment` двигают реальные деньги и **необратимы**. Эти инструменты\n   помечены как разрушающие, чтобы MCP-клиенты спрашивали подтверждение перед запуском.\n4. HTTP-транспорт по умолчанию отказывает без авторизации и слушает localhost — перед любым удалённым\n   развёртыванием прочитайте [SECURITY.md](SECURITY.md).\n\n## Инструменты (20)\n\n### Платежи (9)\n\n| Инструмент | Описание |\n|------|-------------|\n| `create_payment` | Создать платёж с суммой, описанием и способом оплаты. Возвращает ссылку на оплату. Поддерживает чеки и метаданные |\n| `get_payment` | Данные платежа по ID — статус, сумма, ссылка подтверждения, метаданные |\n| `capture_payment` | Подтвердить двухстадийный платёж (списать удержанные средства). Частичное списание поддерживается |\n| `cancel_payment` | Отменить платёж (в статусе pending или waiting_for_capture) |\n| `list_payments` | Список платежей с фильтрами по статусу, периоду и пагинацией |\n| `save_payment_method` | Сохранить способ оплаты для рекуррентных списаний (привязка карты) |\n| `create_recurring_payment` | Списать по сохранённому способу оплаты (без участия пользователя) |\n| `create_sbp_payment` | Создать платёж через СБП (Система быстрых платежей) |\n| `create_split_payment` | Сплит-платёж для маркетплейсов — распределение денег между партнёрами |\n\n### Возвраты (3)\n\n| Инструмент | Описание |\n|------|-------------|\n| `create_refund` | Полный или частичный возврат по ID платежа |\n| `get_refund` | Данные возврата по ID |\n| `list_refunds` | Список возвратов с необязательным фильтром по платежу |\n\n### Чеки (2)\n\n| Инструмент | Описание |\n|------|-------------|\n| `create_receipt` | Фискальный чек (54-ФЗ) — позиции, коды НДС, контакты покупателя |\n| `list_receipts` | Список чеков по ID платежа или возврата |\n\n### Выплаты (2)\n\n> ⚠️ **Выплаты — отдельно подключаемый продукт ЮKassa** со своими реквизитами шлюза\n> (`YOOKASSA_PAYOUT_AGENT_ID` + `YOOKASSA_PAYOUT_SECRET_KEY`), это не платёжный ключ магазина.\n> Передача сырого номера карты требует сертификата PCI DSS — без него собирайте реквизиты получателя\n> через виджет выплат и передавайте `payout_token`. Выплаты асинхронные (опрашивайте `get_payout`).\n\n| Инструмент | Описание |\n|------|-------------|\n| `create_payout` | Выплата на банковскую карту, кошелёк ЮMoney или через СБП, либо по `payout_token` |\n| `get_payout` | Статус и детали выплаты по ID |\n\n### Вебхуки (3)\n\n| Инструмент | Описание |\n|------|-------------|\n| `create_webhook` | Зарегистрировать URL вебхука для событий (payment.succeeded, refund.succeeded и т. д.) |\n| `list_webhooks` | Список всех зарегистрированных вебхуков |\n| `delete_webhook` | Удалить вебхук по ID |\n\n### Аккаунт (1)\n\n| Инструмент | Описание |\n|------|-------------|\n| `get_shop_info` | Информация о магазине — ID, статус, тестовый режим, фискализация (эндпоинта баланса в ЮKassa нет) |\n\n## Демо-промпты\n\n```\nСоздай платёж на 5000 рублей по заказу #123 со способом оплаты СБП\n```\n\n```\nНастрой рекуррентную подписку: привяжи карту списанием 1 рубля, потом списывай 999 рублей ежемесячно по сохранённому способу\n```\n\n```\nПокажи все успешные платежи за последние 7 дней и сделай возврат 2500 рублей по платежу pay_xxx\n```\n\n## Архитектура\n\n- **Авторизация**: HTTP Basic Auth (`YOOKASSA_SHOP_ID:YOOKASSA_SECRET_KEY`)\n- **Базовый URL**: `https://api.yookassa.ru/v3/`\n- **Idempotence-Key**: один стабильный UUID v4 на каждый логический POST/DELETE-запрос, сохраняется при повторах (повторный запрос дедуплицируется на стороне ЮKassa, двойного списания не будет). Вызывающая сторона может передать свой ключ.\n- **Таймаут**: 35 секунд (больше, чем окно ответа ЮKassa ~30 с, чтобы медленная, но успешная операция не обрывалась на клиенте)\n- **Повторы**: 3 попытки на 429/5xx/таймаут с экспоненциальной задержкой (1 с, 2 с, 4 с); повторы переиспользуют тот же Idempotence-Key и безопасно дедуплицируются\n- **Транспорт**: stdio (по умолчанию) или Streamable HTTP (`--http` / `HTTP_PORT`)\n\n## Часть серии WWmcp\n\n| MCP | Статус | Описание |\n|-----|--------|-------------|\n| [@metarebalance/dadata-mcp](https://github.com/theYahia/dadata-mcp) | готов | Адреса, компании, банки, телефоны |\n| [@theyahia/cbr-mcp](https://github.com/theYahia/cbr-mcp) | готов | Курсы валют, ключевая ставка |\n| [@theyahia/yookassa-mcp](https://github.com/theYahia/yookassa-mcp) | готов | Платежи, возвраты, чеки, выплаты, вебхуки |\n| [@theyahia/cloudpayments-mcp](https://github.com/theYahia/cloudpayments-mcp) | готов | Платежи, подписки, заказы |\n| ... | | **46 серверов** — [полный список](https://github.com/theYahia/WWmcp) |\n\n## Лицензия\n\nMIT\n\n---\n\nЧасть [WWmcp](https://github.com/theYahia/WWmcp) · Telegram: [@vhodvai](https://t.me/vhodvai)\n",
  "bytes": 9176,
  "sha": "25bbab5a1ac025f2471f54dfbb15403f7d909e6bc172bc9ecf964119d2824938",
  "repo_slug": "theyahia/yookassa-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_theyahia_yookassa_mcp_92aaf4c7/readme"
}