robokassa-mcp
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., "@robokassa-mcp Create an invoice for 599.00 RUB for order 12345"
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.
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)
# As an MCP server for Claude Desktop / Claude Code / Cursor / Windsurf
uvx robokassa-mcp
# As a Python library
pip install robokassa-mcpRelated MCP server: YooKassa MCP Server
Use as a Python library
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
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)
breakWebhook signature verification (FastAPI example)
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):
{
"mcpServers": {
"robokassa": {
"command": "uvx",
"args": ["robokassa-mcp"],
"env": {
"ROBOKASSA_LOGIN": "your-shop-login",
"ROBOKASSA_PASSWORD1": "password1",
"ROBOKASSA_PASSWORD2": "password2",
"ROBOKASSA_PASSWORD3": "password3"
}
}
}
}Claude Code
claude mcp add robokassa \
-e ROBOKASSA_LOGIN=my-shop \
-e ROBOKASSA_PASSWORD1=... \
-e ROBOKASSA_PASSWORD2=... \
-e ROBOKASSA_PASSWORD3=... \
-- uvx robokassa-mcpCursor
Edit ~/.cursor/mcp.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:
{
"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:
{
"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)
uvx robokassa-mcp --transport http --port 8000Flags: --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 |
| Build a signed checkout URL (optional 54-ФЗ receipt). | Password#1 |
| Get current state of a payment by InvId (via OpStateExt). | Password#2 |
| List payment methods available to the shop. | — |
| Compute amount credited to shop for a given payment. | Password#1 |
| Initiate a refund (requires Refund API access). | Password#3 JWT |
| Poll refund progress by requestId. | — |
| Validate a ResultURL webhook. | Password#2 |
| Validate a SuccessURL redirect. | Password#1 |
| Two-step card pre-authorization. | Password#1 |
| Subscription auto-charges. | Password#1 |
| Marketplace multi-recipient checkout. | — |
| Paid SMS service. | Password#1 |
| 54-ФЗ final receipt after advance. | Password#1 |
| 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 | ✅ |
|
XML Interfaces | ✅ |
|
Refund API | ✅ |
|
Holding / Pre-auth | ✅ init / confirm / cancel |
|
Recurring | ✅ parent + child |
|
Fiscal 54-ФЗ | ✅ second receipt create / status |
|
Partner API | 🟡 |
|
Auxiliary | ✅ |
|
Environment variables
Most high-level entry points fall back to these env vars when credentials aren't passed explicitly:
Variable | Required for |
| All operations |
| Checkout, webhook SuccessURL verification, CalcOutSumm, fiscal, SMS |
|
|
|
|
Signature algorithms
All signature-producing helpers accept algorithm= with "md5" / "sha256" / "sha384" / "sha512" — match whatever is configured in your Robokassa cabinet.
Development
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 pyrightLicense
MIT — see LICENSE. Drop-and-forget maintenance; PRs welcome but not guaranteed to be reviewed promptly.
Available Tools
18 toolsbuild_split_invoiceC
Build a URL for a multi-recipient (marketplace-style) split payment.
Each split: {merchantLogin, amount, description?}. Sum of amounts
must equal out_amount.
Inputs: out_amount (required), splits (required), email, inc_curr, +2 more. Returns: object
calc_out_sumA
Calculate the amount credited to the shop for a given customer payment.
Useful for showing the commission / final sum in checkout UI.
Signature: <algorithm>(MerchantLogin:IncSum:Password#1).
Inputs: inc_sum (required), merchant_login, password1, inc_curr_label, +1 more. Returns: object
check_paymentA
Check the current state of a Robokassa payment by invoice ID.
Uses the OpStateExt XML interface. Returns a structured summary including
the state code (5/10/20/50/60/80/100), the OpKey (required later for
initiating a refund via Refund/Create), sums, payment method, and any
user-defined Shp_* parameters attached at checkout.
State codes: 5 — инициализирована, не оплачена 10 — отменена (таймаут / пользователь) 20 — HOLD (предавторизация) 50 — средства получены, зачисление магазину 60 — отказ в зачислении, средства возвращены покупателю (это НЕ пользовательский refund — для него используйте refund_status) 80 — приостановлена (security check) 100 — оплачена ✅
Credentials may be passed explicitly or via ROBOKASSA_LOGIN / ROBOKASSA_PASSWORD2 environment variables.
Note: OpStateExt does NOT reflect post-payment refunds initiated through the Robokassa cabinet or Refund/Create. For that, store the requestId from Refund/Create and poll Refund/GetState.
Inputs: inv_id (required), merchant_login, password2, algorithm. Returns: object
create_invoiceA
Build a signed Robokassa checkout URL + form fields for a new payment.
Does NOT make an HTTP request — produces the URL to redirect the user to.
Inputs: out_sum (required), inv_id (required), description, merchant_login, +9 more. Returns: object
hold_cancelC
Release a hold without capturing the reserved funds.
Inputs: inv_id (required), merchant_login, password1, algorithm. Returns: object
hold_confirmA
Capture previously-reserved funds for a held transaction.
Cart can be reduced (smaller receipt_items) before capture, but not
increased. Pass the same OutSum (possibly smaller) as the original hold.
Inputs: out_sum (required), inv_id (required), merchant_login, password1, +3 more. Returns: object
hold_initA
Build a checkout URL with StepByStep=true for two-step pre-auth.
Funds are reserved on the card; use hold_confirm to capture or
hold_cancel to release. Max hold window: 7 days.
Notification for successful hold is delivered to ResultURL2 (not the standard ResultURL). Requires prior agreement with Robokassa and only works with card payments.
Inputs: out_sum (required), inv_id (required), description, merchant_login, +7 more. Returns: object
init_recurring_parentA
Build a checkout URL marking the payment as a recurring parent.
After the user pays, the shop can silently charge subsequent amounts
via recurring_charge citing this invoice's inv_id.
Inputs: out_sum (required), inv_id (required), description, merchant_login, +7 more. Returns: object
list_currenciesA
List payment methods / currencies available to a Robokassa shop.
Returns the full catalogue grouped by payment family (BankCard, SBP, SberPay, YandexPay, etc.) with per-method Label, Alias, Name, and min/max transaction bounds where applicable.
The Label values are what you pass as IncCurrLabel when calling
create_invoice to restrict the user to a specific payment method.
No password / signature required — GetCurrencies is a public endpoint.
Inputs: merchant_login, language. Returns: object
partner_refundA
Alternative refund path via Partner API (for CPA / SaaS integrators).
Merchant-only users should prefer refund_create instead (uses Password#3).
Partner API requires RoboxPartnerId and partner-specific auth headers —
typically {"Authorization": "Bearer <partner-jwt>"}.
Inputs: robox_partner_id (required), op_key (required), auth_headers (required), refund_sum, +1 more. Returns: object
recurring_chargeA
Silently charge a recurring subscription payment.
previous_inv_id must be the inv_id of an already-paid parent (created
with init_recurring_parent). Response "OK<InvId>" means accepted,
NOT captured — verify via check_payment.
Inputs: new_inv_id (required), previous_inv_id (required), out_sum (required), description, +5 more. Returns: object
refund_createA
Initiate a refund for a successful Robokassa payment.
Requires op_key — obtained from check_payment (OpStateExt) or the
Result2 webhook payload for the original operation.
Refund amount:
- Omit refund_sum for a FULL refund of the original operation.
- Pass a numeric amount for a partial refund.
Fiscal receipt:
- Omit items to refund without emitting a fiscal receipt (appropriate
when the original sale was not fiscalized through Robokassa).
- Pass a list of items to emit a receipt for the refund. Each item:
{name, quantity, cost, tax, payment_method, payment_object} where
tax ∈ none/vat0/vat5/vat7/vat10/vat20/vat105/vat107/vat110/vat120,
payment_method ∈ full_payment/advance/..., payment_object ∈
commodity/service/payment/...
Authentication:
Uses JWT signed with Password#3. This is distinct from Password#1
(checkout) and Password#2 (XML status). Access to the Refund API must
be enabled in the Robokassa cabinet separately.
Returns:
{success: bool, request_id: str | None, message: str | None}.
Store request_id to poll refund status via refund_status.
Common failure messages: NotEnoughOperationFunds, OperationNotFound,
AlreadyRefunded.
Credentials may be passed explicitly or via the ROBOKASSA_PASSWORD3 env var.
Inputs: op_key (required), password3, refund_sum, items, +1 more. Returns: object
refund_statusA
Check the current state of a previously-created refund request.
Inputs: request_id (required). Returns: object
second_receipt_createA
Emit a final (second) 54-ФЗ fiscal receipt after an advance/prepayment sale.
For merchants using Robokassa Fiscal. merchant_id is the Fiscal
merchantId (e.g. robokassa_sell); origin_id is the InvId of the
original operation. Max 2 receipts per operation.
items: [{name, quantity, sum, tax, payment_method, payment_object}].
payments: typically [{type: 2, sum: <total>}] for offsetting a prepayment.
client: {email} or {phone}.
Inputs: merchant_id (required), receipt_id (required), origin_id (required), items (required), +7 more. Returns: object
second_receipt_statusA
Check registration status of a 54-ФЗ fiscal receipt.
Use merchant_id="robokassa_state" for status lookups.
Inputs: merchant_id (required), receipt_id (required), password1. Returns: object
send_smsA
Send an SMS via Robokassa's SMS service.
Paid feature — requires a non-zero SMS balance in the cabinet.
Phone must be in international format (e.g. 79991234567).
Inputs: phone (required), message (required), merchant_login, password1, +1 more. Returns: object
verify_result_signatureA
Verify the SignatureValue on a Robokassa ResultURL request.
Robokassa POSTs payment notifications to the merchant's ResultURL after a
successful checkout. The merchant must verify the signature to confirm the
notification is authentic, then respond with the string returned by
build_ok_response(inv_id) — otherwise Robokassa retries.
Inputs: params (required), password2, algorithm. Returns: object
verify_success_signatureA
Verify the SignatureValue on a Robokassa SuccessURL redirect.
SuccessURL is the browser-side redirect after payment completes. Unlike ResultURL it does NOT mean the payment is credited — only that the user returned to the success page. Still, verifying the signature guards against CSRF / tampering.
Inputs: params (required), password1, algorithm. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools have clearly distinct purposes (e.g., hold_init, hold_confirm, hold_cancel are separate steps). The only potential confusion is between refund_create and partner_refund, but descriptions clarify the difference. Overall, tools are well-differentiated.
Tool names predominantly follow a verb_noun pattern (e.g., build_split_invoice, create_invoice). A few deviate (hold_cancel, hold_confirm), but the naming is still predictable and readable.
With 18 tools covering standard payments, holds, recurring, refunds, fiscal receipts, and utilities, the count is slightly high but well-justified for a comprehensive payment MCP server.
The tool surface covers core payment lifecycle operations. Missing an explicit cancel payment tool for non-hold payments, but agents can work around via states. Overall, nearly complete for the domain.
Maintenance
Related MCP Connectors
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Split bills and collect payments through PayNow (Singapore) from your AI. MCP server for SplitBill.
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
MCP server for MaxMind minFraud — score transactions for fraud risk from your AI assistant.
Related MCP Servers
AlicenseNot gradedqualityCmaintenanceAn MCP server that enables AI agents to accept Bitcoin Lightning payments. It allows agents to create orders, generate invoices, check payment status, and manage the full SatsRail merchant API through natural language.MIT- 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
- FlicenseNot gradedqualityBmaintenanceA local MCP server that lets AI agents interact with the Adaptis (MEG) payment gateway, enabling payment link creation, transaction queries, refunds, and integration helpers like generating signed forms and verifying callbacks.-
- AlicenseAqualityCmaintenanceMCP server for Robokassa payment API. 2 tools for invoice creation (with MD5 signature) and status checking.21MIT