Yookassa Mcp

io.github.theYahiaPublished by GitHub account theYahiav1.0.0Updated Oct 24, 2026

MCP server for YooKassa payment API — payments, refunds, receipts (54-FZ). 10 tools. First MCP for

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Lets an assistant run YooKassa payment operations — payments, refunds, receipts, payouts and webhooks — from a chat.

What you can do
Wraps the YooKassa payment API in about 20 tools covering payments (create, capture, cancel, list, SBP, split, recurring), refunds, 54-FZ fiscal receipts, payouts, webhooks and shop info. It returns payment confirmation links and supports idempotency keys and retries. It runs locally over stdio by default, or as a Streamable HTTP endpoint when started with the HTTP flag.
When to use it
Use it when you want an assistant to create or inspect real YooKassa payments, issue refunds, generate fiscal receipts, register webhooks or make payouts without writing integration code. Test it against a YooKassa test shop before pointing it at a live shop.
Requirements
Node.js to run the npm package via npx. A YooKassa shop ID and secret key (YOOKASSA_SHOP_ID, YOOKASSA_SECRET_KEY); payouts additionally need YOOKASSA_PAYOUT_AGENT_ID and YOOKASSA_PAYOUT_SECRET_KEY. HTTP mode needs MCP_AUTH_TOKEN and optionally HTTP_PORT, HTTP_HOST, MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS. Network access to the YooKassa API.
Before you install
The server performs real money operations: create_payment, create_refund, create_payout, create_recurring_payment, save_payment_method and capture_payment are irreversible in a live shop and are marked destructive so clients ask for confirmation. It handles payment credentials (YOOKASSA_SHOP_ID, YOOKASSA_SECRET_KEY, payout keys) and an HTTP bearer token (MCP_AUTH_TOKEN). HTTP mode exposes money-moving tools, so keep it on localhost behind an authenticated proxy and never expose it directly to…

Installation

In SourceWeft

  1. Open Yookassa Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

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

[npm] [CI] [License: MIT] [smithery badge]

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

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

Claude Desktop

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

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

VS Code / Cursor

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

Windsurf

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

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

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

  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

Source: README.md at commit 35231b2

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts