@theyahia/yookassa-mcp

MCP-сервер для ЮKassa API: платежи, возвраты, чеки 54-ФЗ. 10 инструментов. Первый MCP-сервер для ЮKassa.

Часть серии Russian API MCP (50 серверов) by @theYahia.

Quick Start

Claude Desktop

Файл: claude_desktop_config.json

{
  "mcpServers": {
    "yookassa": {
      "command": "npx",
      "args": ["-y", "@theyahia/yookassa-mcp"],
      "env": {
        "YOOKASSA_SHOP_ID": "ваш-shop-id",
        "YOOKASSA_SECRET_KEY": "ваш-секретный-ключ"
      }
    }
  }
}

Claude Code

claude mcp add yookassa -e YOOKASSA_SHOP_ID=ваш-id -e YOOKASSA_SECRET_KEY=ваш-ключ -- npx -y @theyahia/yookassa-mcp

VS Code / Cursor

Файл: .vscode/mcp.json

{
  "servers": {
    "yookassa": {
      "command": "npx",
      "args": ["-y", "@theyahia/yookassa-mcp"],
      "env": {
        "YOOKASSA_SHOP_ID": "ваш-shop-id",
        "YOOKASSA_SECRET_KEY": "ваш-секретный-ключ"
      }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "yookassa": {
      "command": "npx",
      "args": ["-y", "@theyahia/yookassa-mcp"],
      "env": {
        "YOOKASSA_SHOP_ID": "ваш-shop-id",
        "YOOKASSA_SECRET_KEY": "ваш-секретный-ключ"
      }
    }
  }
}

Streamable HTTP (remote / Docker)

HTTP_PORT=3000 npx -y @theyahia/yookassa-mcp --http

Или через переменную окружения:

export HTTP_PORT=3000
npx -y @theyahia/yookassa-mcp

Эндпоинты:

• POST /mcp — MCP Streamable HTTP transport
• GET /health — health check ({ "status": "ok", "tools": 10 })

CORS включён для всех origin.

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

Для тестирования создайте демо-магазин в личном кабинете ЮKassa.

Инструменты (10)

Платежи (5)

Возвраты (3)

Чеки 54-ФЗ (1)

Аккаунт (1)

Примеры запросов

Создать платёж:

Создай платёж на 5000 рублей для заказа #123

Возврат:

Сделай возврат по платежу pay_xxx на 2500 рублей

Список платежей:

Покажи все успешные платежи за последние 7 дней

Чек 54-ФЗ:

Создай чек для платежа pay_xxx, email покупателя test@example.com, товар "Консультация" 5000р НДС 20%

Статус магазина:

Какой статус моего магазина?

Чеки 54-ФЗ

Сервер поддерживает формирование кассовых чеков по 54-ФЗ через инструмент create_receipt.

Параметры чека:

• type — payment (приход) или refund (возврат прихода)
• payment_id — ID платежа
• customer_email — email покупателя (обязателен для отправки чека)
• items — массив товаров/услуг:
  • description — название
  • quantity — количество
  • amount — цена за единицу (рубли)
  • vat_code — код НДС:
    • 1 — без НДС
    • 2 — НДС 0%
    • 3 — НДС 10%
    • 4 — НДС 20%
    • 5 — НДС 10/110
    • 6 — НДС 20/120

Для работы чеков необходимо подключить фискализацию в личном кабинете ЮKassa.

Архитектура

• Auth: HTTP Basic Auth (YOOKASSA_SHOP_ID:YOOKASSA_SECRET_KEY)
• Base URL: https://api.yookassa.ru/v3/
• Idempotence-Key: UUID v4 в каждом POST-запросе
• Timeout: 10 секунд
• Retry: 3 попытки на 429/5xx с экспоненциальным backoff (1s, 2s, 4s)
• Транспорт: stdio (по умолчанию) или Streamable HTTP (--http / HTTP_PORT)

Синергия с dadata-mcp

Проверка контрагента перед оплатой:

1. dadata-mcp: find_company_by_id(ИНН) → проверить что компания активна
2. yookassa-mcp: create_payment(amount, description) → получить ссылку на оплату
3. yookassa-mcp: get_payment(id) → проверить статус

Часть серии Russian API MCP

Лицензия

MIT