Skip to main content
Glama
@theyahia/yookassa-mcp

@theyahia/yookassa-mcp

by theYahia

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

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

npm CI License: MIT

Часть серии 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> })

Related MCP server: robokassa-mcp

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

Переменная

Обяз.

Описание

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

Available Tools

20 tools
cancel_paymentCancel paymentA
DestructiveIdempotent

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 paymentA
DestructiveIdempotent

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 paymentA
Destructive

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 payoutA
Destructive

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 receiptA
Destructive

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 paymentA
Destructive

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 refundA
Destructive

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 paymentA
Destructive

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 paymentA
Destructive

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 webhookB
Destructive

Register a webhook URL for YooKassa events (payment.succeeded, refund.succeeded, etc.).

Inputs: url (required), event (required).

delete_webhookDelete webhookA
DestructiveIdempotent

Delete a webhook by ID. Stops sending notifications for that webhook.

Inputs: webhook_id (required).

get_paymentGet paymentA
Read-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 payoutA
Read-only

Get payout details by ID. Returns status, amount, and destination.

Inputs: payout_id (required). Returns: id, paid, amount, status, +1 more

get_refundGet refundA
Read-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 infoA
Read-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 paymentsA
Read-only

List payments with filters by status, date range, and pagination cursor.

Inputs: limit, cursor, status, created_at_gte, +1 more.

list_receiptsList receiptsA
Read-only

List receipts with filters by payment_id or refund_id.

Inputs: limit, cursor, refund_id, payment_id.

list_refundsList refundsA
Read-only

List refunds with optional filter by payment_id.

Inputs: limit, payment_id.

list_webhooksList webhooksA
Read-only

List all registered webhooks for this shop.

Inputs: no named parameters.

save_payment_methodSave payment methodA
Destructive

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

    A4/5.0

    Scored across 20 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      MCP 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 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      18
      26 PyPI
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP server for lolzteam/lzt.market ecosystem providing 29 tools for raw API requests, flow scenario management, event subscriptions, and API introspection.
      29
      MIT