@theyahia/yookassa-mcp

MCP server for YooKassa API -- payments, refunds, receipts (54-FZ), payouts, webhooks, recurring, SBP, marketplace splits. 20 tools.

Part of Russian API MCP series by @theYahia.

Quick Start

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 (remote / Docker)

⚠️ The HTTP transport exposes money-moving tools. It requires a Bearer token, binds to 127.0.0.1 by default, and validates Host/Origin (DNS-rebinding protection). Never expose it directly to the internet — put it behind an authenticating reverse proxy / mTLS. See SECURITY.md.

MCP_AUTH_TOKEN="$(openssl rand -hex 32)" HTTP_PORT=3000 npx -y @theyahia/yookassa-mcp --http

Then call /mcp with Authorization: Bearer <MCP_AUTH_TOKEN>.

Endpoints:

• POST /mcp -- MCP Streamable HTTP transport (Bearer auth required; stateless — POST only)
• GET /health -- unauthenticated health check ({ "status": "ok", "tools": <count> })

Environment Variables

Test mode / safety

This server drives real money operations. While developing:

1. Create a test shop in the YooKassa dashboard and

use its YOOKASSA_SHOP_ID / YOOKASSA_SECRET_KEY.

1. Confirm you are in test mode by calling `get_shop_info` — expect "test": true — before

switching to a live shop.

1. In a live shop, create_payment, create_refund, create_payout, create_recurring_payment,

save_payment_method, and capture_payment move real funds and are irreversible. These tools are annotated as destructive so MCP clients can prompt before running them.

1. The HTTP transport is unauthenticated-by-default-refused and binds to localhost — see

SECURITY.md before any remote deployment.

Tools (20)

Payments (9)

Refunds (3)

Receipts (2)

Payouts (2)

⚠️ Payouts are a separately-activated YooKassa product with their own gateway credentials (YOOKASSA_PAYOUT_AGENT_ID + YOOKASSA_PAYOUT_SECRET_KEY), not the shop's payment key. Sending a raw card number requires a PCI DSS certificate — without it, collect the recipient via the payout widget and pass payout_token. Payouts are asynchronous (poll get_payout).

Webhooks (3)

Account (1)

Demo Prompts

Create a payment for 5000 RUB for order #123 with SBP as payment method

Set up a recurring subscription: bind the card with 1 ruble, then charge 999 RUB monthly using the saved method

Show all successful payments for the last 7 days and create a refund of 2500 RUB for payment pay_xxx

Architecture

• Auth: HTTP Basic Auth (YOOKASSA_SHOP_ID:YOOKASSA_SECRET_KEY)
• Base URL: https://api.yookassa.ru/v3/
• Idempotence-Key: one stable UUID v4 per logical POST/DELETE request, preserved across retries (a retried request is de-duplicated by YooKassa, never double-charged). Callers may pass an explicit key.
• Timeout: 35 seconds (above YooKassa's ~30s server-side answer window, so slow-but-successful operations are not aborted client-side)
• Retry: 3 attempts on 429/5xx/timeout with exponential backoff (1s, 2s, 4s); retries reuse the same Idempotence-Key, so they are safely de-duplicated
• Transport: stdio (default) or Streamable HTTP (--http / HTTP_PORT)

Part of Russian API MCP Series

License

MIT