robokassa-mcp — Robokassa payment gateway exposed to AI agents through MCP

robokassa-mcp

📚 Documentation · PyPI · Docker · MCP Registry

Comprehensive Python client and Model Context Protocol server for Robokassa — the Russian payment gateway.

Covers the full API surface: checkout, XML status interfaces, refunds, holding (pre-auth), recurring subscriptions, 54-ФЗ fiscal receipts, Partner API, and auxiliary endpoints.

Install (once published)

bash

# As an MCP server for Claude Desktop / Claude Code / Cursor / Windsurf
uvx robokassa-mcp

# As a Python library
pip install robokassa-mcp

Use as a Python library

server.ts

import asyncio
from decimal import Decimal
from robokassa import create_invoice, RobokassaClient

# Build a signed checkout URL (no HTTP — just URL construction).
invoice = create_invoice(
    merchant_login="my-shop",
    out_sum=Decimal("599.00"),
    inv_id=12345,
    password1="...",
    description="Premium subscription",
    email="user@example.com",
)
print(invoice.url)  # https://auth.robokassa.ru/Merchant/Index.aspx?...

# Check the state of a payment (hits the OpStateExt XML endpoint).
async def check() -> None:
    async with RobokassaClient("my-shop", password2="...") as client:
        state = await client.check_payment(inv_id=12345)
        print(state.is_paid, state.info.op_key)

asyncio.run(check())

Full refund flow

server.ts

from robokassa import RobokassaClient

async def refund_flow(inv_id: int) -> None:
    async with RobokassaClient("my-shop", password2="p2", password3="p3") as client:
        # 1. Fetch the payment state to get its OpKey.
        state = await client.check_payment(inv_id)
        assert state.info.op_key, "payment not complete yet"

        # 2. Initiate a refund.
        created = await client.refund_create(state.info.op_key)
        print("refund requestId:", created.request_id)

        # 3. Poll status until finished / canceled.
        while True:
            status = await client.refund_status(created.request_id)
            if status.is_terminal:
                print("final:", status.state)
                break

Webhook signature verification (FastAPI example)

server.ts

from fastapi import FastAPI, Request, HTTPException, PlainTextResponse
from robokassa import verify_result_signature, build_ok_response

app = FastAPI()

@app.post("/robokassa/result")
async def result_url(req: Request) -> PlainTextResponse:
    form = dict(await req.form())
    if not verify_result_signature(form, password2="..."):
        raise HTTPException(status_code=403, detail="Bad signature")
    # ... persist the notification, mark invoice paid ...
    return PlainTextResponse(build_ok_response(form["InvId"]))

Use as an MCP server

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

config.json

{
  "mcpServers": {
    "robokassa": {
      "command": "uvx",
      "args": ["robokassa-mcp"],
      "env": {
        "ROBOKASSA_LOGIN": "your-shop-login",
        "ROBOKASSA_PASSWORD1": "password1",
        "ROBOKASSA_PASSWORD2": "password2",
        "ROBOKASSA_PASSWORD3": "password3"
      }
    }
  }
}

Claude Code

Terminal

claude mcp add robokassa \
  -e ROBOKASSA_LOGIN=my-shop \
  -e ROBOKASSA_PASSWORD1=... \
  -e ROBOKASSA_PASSWORD2=... \
  -e ROBOKASSA_PASSWORD3=... \
  -- uvx robokassa-mcp

Cursor

Edit ~/.cursor/mcp.json:

config.json

{
  "mcpServers": {
    "robokassa": {
      "command": "uvx",
      "args": ["robokassa-mcp"],
      "env": {
        "ROBOKASSA_LOGIN": "your-shop-login",
        "ROBOKASSA_PASSWORD1": "password1",
        "ROBOKASSA_PASSWORD2": "password2",
        "ROBOKASSA_PASSWORD3": "password3"
      }
    }
  }
}

VS Code (GitHub Copilot)

In user or workspace settings.json:

config.json

{
  "github.copilot.chat.mcp.servers": {
    "robokassa": {
      "command": "uvx",
      "args": ["robokassa-mcp"],
      "env": {
        "ROBOKASSA_LOGIN": "your-shop-login",
        "ROBOKASSA_PASSWORD1": "password1",
        "ROBOKASSA_PASSWORD2": "password2",
        "ROBOKASSA_PASSWORD3": "password3"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

config.json

{
  "mcpServers": {
    "robokassa": {
      "command": "uvx",
      "args": ["robokassa-mcp"],
      "env": {
        "ROBOKASSA_LOGIN": "your-shop-login",
        "ROBOKASSA_PASSWORD1": "password1",
        "ROBOKASSA_PASSWORD2": "password2",
        "ROBOKASSA_PASSWORD3": "password3"
      }
    }
  }
}

HTTP transport (MCP Inspector, remote clients)

bash

uvx robokassa-mcp --transport http --port 8000

Flags: --transport {stdio,http,streamable-http,sse}, --host, --port.

MCP tools exposed to agents

All 18 tools are wrapped as @mcp.tool() and available to any MCP-capable agent (Claude Desktop, Claude Code, Cursor, Windsurf, etc.).

Tool	Purpose	Auth
`create_invoice`	Build a signed checkout URL (optional 54-ФЗ receipt).	Password#1
`check_payment`	Get current state of a payment by InvId (via OpStateExt).	Password#2
`list_currencies`	List payment methods available to the shop.	—
`calc_out_sum`	Compute amount credited to shop for a given payment.	Password#1
`refund_create`	Initiate a refund (requires Refund API access).	Password#3 JWT
`refund_status`	Poll refund progress by requestId.	—
`verify_result_signature`	Validate a ResultURL webhook.	Password#2
`verify_success_signature`	Validate a SuccessURL redirect.	Password#1
`hold_init` / `hold_confirm` / `hold_cancel`	Two-step card pre-authorization.	Password#1
`init_recurring_parent` / `recurring_charge`	Subscription auto-charges.	Password#1
`build_split_invoice`	Marketplace multi-recipient checkout.	—
`send_sms`	Paid SMS service.	Password#1
`second_receipt_create` / `second_receipt_status`	54-ФЗ final receipt after advance.	Password#1
`partner_refund`	Alternative refund path for partner integrators.	Partner JWT

Low-level signature helpers are available from Python only: compute_signature, op_state_signature, build_checkout_signature, build_refund_jwt, build_sms_signature, compute_result_signature, compute_success_signature, encode_fiscal_body.

API coverage

Mapped against the 8 public Robokassa API groups:

Group	Coverage	Module
Merchant Checkout	✅ `create_invoice` (+ 54-ФЗ)	`robokassa.checkout`
XML Interfaces	✅ `check_payment`, `list_currencies`, `calc_out_sum`	`robokassa.xml_interface`
Refund API	✅ `refund_create`, `refund_status`	`robokassa.refund`
Holding / Pre-auth	✅ init / confirm / cancel	`robokassa.holding`
Recurring	✅ parent + child	`robokassa.recurring`
Fiscal 54-ФЗ	✅ second receipt create / status	`robokassa.fiscal`
Partner API	🟡 `partner_refund` only — see coverage notes	`robokassa.partner`
Auxiliary	✅ `send_sms`, webhook signatures, split payments	`robokassa.sms`, `robokassa.webhooks`, `robokassa.split`

Environment variables

Most high-level entry points fall back to these env vars when credentials aren't passed explicitly:

Variable	Required for
`ROBOKASSA_LOGIN`	All operations
`ROBOKASSA_PASSWORD1`	Checkout, webhook SuccessURL verification, CalcOutSumm, fiscal, SMS
`ROBOKASSA_PASSWORD2`	`check_payment` (OpStateExt), webhook ResultURL verification
`ROBOKASSA_PASSWORD3`	`refund_create`

Signature algorithms

All signature-producing helpers accept algorithm= with "md5" / "sha256" / "sha384" / "sha512" — match whatever is configured in your Robokassa cabinet.

Development

bash

git clone https://github.com/artgas1/robokassa-mcp.git
cd robokassa-mcp
uv sync --all-extras --dev
uv run pytest            # 107+ unit tests
uv run ruff check .
uv run pyright

License

MIT — see LICENSE. Drop-and-forget maintenance; PRs welcome but not guaranteed to be reviewed promptly.