@theyahia/yookassa-mcp
This server integrates YooKassa (Russian payment provider) into MCP, letting AI agents manage payments, refunds, receipts, payouts, webhooks, and shop info — with real-money operations flagged as destructive.
Payments: create payments (including SBP, split-payments for marketplaces, recurring/SAVE payment method), get, capture, cancel, and list payments with filters.
Recurring: save a payment method and charge it later without user interaction.
Refunds: create full/partial refunds, get refund details, list refunds by payment.
Fiscal receipts: create standalone 54-FZ receipts (payment/refund) with items, VAT codes, settlements, and customer contacts; list receipts by payment/refund.
Payouts: create payouts to bank cards, YooMoney wallets, or SBP (via payout_token or raw details where PCI DSS allows); poll payout status.
Webhooks: register, list, and delete webhook subscriptions for YooKassa events.
Shop info: retrieve shop ID, status, test mode, and fiscalization settings.
Safety: supports test-mode verification, idempotency keys, timeouts/retries; all money-moving actions are marked destructive/irreversible.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@theyahia/yookassa-mcp Create a payment for 5000 RUB for order #123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ю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-mcpVS 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> })
Related MCP server: robokassa-mcp
Переменные окружения
Переменная | Обяз. | Описание |
| да | ID магазина (Настройки → Магазин) |
| да | Секретный ключ (Интеграция → Ключи API) |
| для выплат | ID шлюза (agentId) продукта «Выплаты» (Настройки → Выплаты) |
| для выплат | Секретный ключ шлюза выплат |
| нет | Порт HTTP-транспорта (по умолчанию 3000); включает режим |
| только HTTP | Обязателен в HTTP-режиме. Bearer-токен, который клиенты шлют на |
| нет | Адрес привязки в HTTP-режиме (по умолчанию |
| нет | Список разрешённых |
| нет | Список разрешённых браузерных |
| нет |
|
Тестовый режим и безопасность
Сервер выполняет реальные денежные операции. На время разработки:
Заведите тестовый магазин в личном кабинете Ю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)
Инструмент | Описание |
| Создать платёж с суммой, описанием и способом оплаты. Возвращает ссылку на оплату. Поддерживает чеки и метаданные |
| Данные платежа по ID — статус, сумма, ссылка подтверждения, метаданные |
| Подтвердить двухстадийный платёж (списать удержанные средства). Частичное списание поддерживается |
| Отменить платёж (в статусе pending или waiting_for_capture) |
| Список платежей с фильтрами по статусу, периоду и пагинацией |
| Сохранить способ оплаты для рекуррентных списаний (привязка карты) |
| Списать по сохранённому способу оплаты (без участия пользователя) |
| Создать платёж через СБП (Система быстрых платежей) |
| Сплит-платёж для маркетплейсов — распределение денег между партнёрами |
Возвраты (3)
Инструмент | Описание |
| Полный или частичный возврат по ID платежа |
| Данные возврата по ID |
| Список возвратов с необязательным фильтром по платежу |
Чеки (2)
Инструмент | Описание |
| Фискальный чек (54-ФЗ) — позиции, коды НДС, контакты покупателя |
| Список чеков по ID платежа или возврата |
Выплаты (2)
⚠️ Выплаты — отдельно подключаемый продукт ЮKassa со своими реквизитами шлюза (
YOOKASSA_PAYOUT_AGENT_ID+YOOKASSA_PAYOUT_SECRET_KEY), это не платёжный ключ магазина. Передача сырого номера карты требует сертификата PCI DSS — без него собирайте реквизиты получателя через виджет выплат и передавайтеpayout_token. Выплаты асинхронные (опрашивайтеget_payout).
Инструмент | Описание |
| Выплата на банковскую карту, кошелёк ЮMoney или через СБП, либо по |
| Статус и детали выплаты по ID |
Вебхуки (3)
Инструмент | Описание |
| Зарегистрировать URL вебхука для событий (payment.succeeded, refund.succeeded и т. д.) |
| Список всех зарегистрированных вебхуков |
| Удалить вебхук по ID |
Аккаунт (1)
Инструмент | Описание |
| Информация о магазине — 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 | Статус | Описание |
готов | Адреса, компании, банки, телефоны | |
готов | Курсы валют, ключевая ставка | |
готов | Платежи, возвраты, чеки, выплаты, вебхуки | |
готов | Платежи, подписки, заказы | |
... | 46 серверов — полный список |
Лицензия
MIT
Available Tools
20 toolscancel_paymentCancel paymentADestructiveIdempotent
Cancel a payment (pending or waiting_for_capture). Releases any held funds.
Inputs: payment_id (required). Returns: id, paid, amount, status, +1 more
capture_paymentCapture paymentADestructiveIdempotent
Confirm a two-step payment (capture held funds). Optionally capture a partial amount. MOVES REAL MONEY — irreversible.
Inputs: payment_id (required), amount. Returns: id, paid, amount, status, +1 more
create_paymentCreate paymentADestructive
Create a payment in YooKassa. Returns a confirmation URL. Supports one-step and two-step payments, receipts, and metadata. MOVES REAL MONEY (the payer is charged) — irreversible.
Inputs: amount (required), description (required), capture, currency, +7 more. Returns: id, paid, amount, status, +1 more
create_payoutCreate payoutADestructive
Create a payout to a bank card, YooMoney wallet, or SBP. Requires the separately-activated YooKassa Payouts product with its own credentials (see README/SECURITY). Asynchronous — the response may be 'pending'; poll get_payout for the final status. MOVES REAL MONEY — irreversible.
Inputs: amount (required), bank_id, currency, metadata, +4 more. Returns: id, paid, amount, status, +1 more
create_receiptCreate receiptADestructive
Create a standalone fiscal receipt (54-FZ). Supports payment and refund receipts with items, VAT codes, and customer contacts.
Inputs: type (required), items (required), send, refund_id, +6 more.
create_recurring_paymentCreate recurring paymentADestructive
Charge a saved payment method. Charges the card immediately WITHOUT any user interaction. MOVES REAL MONEY — irreversible.
Inputs: amount (required), description (required), payment_method_id (required), currency. Returns: id, paid, amount, status, +1 more
create_refundCreate refundADestructive
Refund a payment (full or partial) by payment_id and amount. MOVES REAL MONEY (funds returned to the payer) — irreversible.
Inputs: amount (required), payment_id (required), description. Returns: id, paid, amount, status, +1 more
create_sbp_paymentCreate SBP paymentADestructive
Create a payment via SBP (Russian fast payment system). Returns a confirmation URL / deep-link for the payer's banking app. MOVES REAL MONEY — irreversible.
Inputs: amount (required), description (required), currency, return_url, +1 more. Returns: id, paid, amount, status, +1 more
create_split_paymentCreate split paymentADestructive
Create a split payment for marketplaces (distributes funds among partner shops). Requires the YooKassa-for-platforms product. MOVES REAL MONEY — irreversible.
Inputs: amount (required), transfers (required), description (required), currency, +2 more. Returns: id, paid, amount, status, +1 more
create_webhookCreate webhookBDestructive
Register a webhook URL for YooKassa events (payment.succeeded, refund.succeeded, etc.).
Inputs: url (required), event (required).
delete_webhookDelete webhookADestructiveIdempotent
Delete a webhook by ID. Stops sending notifications for that webhook.
Inputs: webhook_id (required).
get_paymentGet paymentARead-only
Get payment details by ID. Returns status, amount, payment method, confirmation URL, and metadata.
Inputs: payment_id (required). Returns: id, paid, amount, status, +1 more
get_payoutGet payoutARead-only
Get payout details by ID. Returns status, amount, and destination.
Inputs: payout_id (required). Returns: id, paid, amount, status, +1 more
get_refundGet refundARead-only
Get refund details by ID. Returns status, amount, and payment reference.
Inputs: refund_id (required). Returns: id, paid, amount, status, +1 more
get_shop_infoGet shop infoARead-only
Get shop info: ID, status, test mode, fiscalization settings. (YooKassa has no balance endpoint; this returns shop configuration, not a monetary balance.)
Inputs: no named parameters.
list_paymentsList paymentsARead-only
List payments with filters by status, date range, and pagination cursor.
Inputs: limit, cursor, status, created_at_gte, +1 more.
list_receiptsList receiptsARead-only
List receipts with filters by payment_id or refund_id.
Inputs: limit, cursor, refund_id, payment_id.
list_refundsList refundsARead-only
List refunds with optional filter by payment_id.
Inputs: limit, payment_id.
list_webhooksList webhooksARead-only
List all registered webhooks for this shop.
Inputs: no named parameters.
save_payment_methodSave payment methodADestructive
Save a payment method for recurring charges. Creates a small real payment to bind the card/wallet (charged, then refundable). MOVES REAL MONEY — irreversible.
Inputs: amount (required), return_url (required), currency, description, +1 more. Returns: id, paid, amount, status, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Tools are largely distinct by resource and action, but the multiple 'create payment' variants (standard, SBP, split, recurring) could cause initial confusion. Descriptions clarify their unique purposes, so agents can differentiate with careful reading.
All tools follow a consistent verb_noun snake_case pattern (create_, get_, list_, capture_, cancel_, delete_, save_). The pattern is predictable and makes the function of each tool immediately clear.
20 tools covers a broad payment API surface, but each tool maps to a distinct operation (payments, refunds, receipts, payouts, webhooks, shop info). The count is slightly above the ideal 3-15 range, but justified by the domain's complexity.
The core payment lifecycle is well covered (create, get, list, capture, cancel), along with refunds, receipts, payouts, and webhooks. Missing list_payouts and a get_receipt are minor gaps, but agents can still perform essential workflows.
Maintenance
Related MCP Connectors
Billing proxy for MCP servers. Adds Stripe and x402 crypto payments without writing billing code.
MCP server integrating with Stripe - tools for customers, products, payments, and more.
MCP servers for Yandex APIs: Wordstat, Search, Webmaster, Metrika, Direct. Open source, by Seyka AI.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceMCP server for T-Kassa (T-Bank/Tinkoff) payment API. Provides 16 tools for payments, refunds, recurring charges, customer management, saved cards, SBP, receipts, and T-Invest portfolio.57 npmMIT
- AlicenseAqualityDmaintenanceMCP server for the Robokassa payment gateway, enabling AI agents to create invoices, check payments, process refunds, manage recurring subscriptions, and handle fiscal receipts via natural language.1826 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for the YooKassa payment API, enabling AI assistants to manage payments, refunds, receipts, webhooks, and saved payment methods through natural language.MIT
- AlicenseBqualityCmaintenanceMCP server for lolzteam/lzt.market ecosystem providing 29 tools for raw API requests, flow scenario management, event subscriptions, and API introspection.29MIT