Robokassa Mcp

robokassa-mcp

📚 文档  ·  PyPI  ·  Docker  ·  MCP 注册表

---

面向 Robokassa（俄罗斯支付网关）的完整 Python 客户端和 Model Context Protocol 服务。

覆盖完整 API：结账、XML 状态接口、退款、预授权、定期订阅、54-ФЗ 财务收据、Partner API 和辅助端点。

安装（发布后）

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

# As a Python library
pip install robokassa-mcp

作为 Python 库使用

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="[email protected]",
)
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())

完整退款流程

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 签名验证（FastAPI 示例）

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"]))

作为 MCP 服务使用

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %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-mcp

Cursor

编辑 ~/.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）

在用户或工作区的 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

编辑 ~/.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 传输（MCP Inspector、远程客户端）

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

标志：--transport {stdio,http,streamable-http,sse}、--host、--port。

向 Agent 暴露的 MCP 工具

全部 18 个工具都封装为 @mcp.tool()，可供任何支持 MCP 的 Agent 使用（Claude Desktop、Claude Code、Cursor、Windsurf 等）。

工具	用途	身份验证
create_invoice	构建经过签名的结账 URL（可选 54-ФЗ 收据）。	Password#1
check_payment	根据 InvId 获取付款当前状态（通过 OpStateExt）。	Password#2
list_currencies	列出商店可用的付款方式。	—
calc_out_sum	计算指定付款中记入商店的金额。	Password#1
refund_create	发起退款（需要 Refund API 访问权限）。	Password#3 JWT
refund_status	根据 requestId 查询退款进度。	—
verify_result_signature	验证 ResultURL webhook。	Password#2
verify_success_signature	验证 SuccessURL 重定向。	Password#1
hold_init / hold_confirm / hold_cancel	两步式银行卡预授权。	Password#1
init_recurring_parent / recurring_charge	订阅自动扣款。	Password#1
build_split_invoice	面向多个收款方的电商平台结账。	—
send_sms	付费短信服务。	Password#1
second_receipt_create / second_receipt_status	预付款后的 54-ФЗ 最终收据。	Password#1
partner_refund	面向合作伙伴集成商的备用退款路径。	Partner JWT

低级签名辅助函数仅可通过 Python 使用：compute_signature、op_state_signature、build_checkout_signature、build_refund_jwt、build_sms_signature、compute_result_signature、compute_success_signature、encode_fiscal_body。

API 覆盖范围

根据 Robokassa 的 8 个公开 API 组进行映射：

组	覆盖范围	模块
商户结账	✅ create_invoice（+ 54-ФЗ）	robokassa.checkout
XML 接口	✅ check_payment、list_currencies、calc_out_sum	robokassa.xml_interface
Refund API	✅ refund_create、refund_status	robokassa.refund
资金冻结 / 预授权	✅ 初始化 / 确认 / 取消	robokassa.holding
定期扣款	✅ 父项 + 子项	robokassa.recurring
财政 54-ФЗ	✅ 创建 / 查询第二张收据	robokassa.fiscal
合作伙伴 API	🟡 仅 partner_refund — 查看覆盖范围说明	robokassa.partner
辅助功能	✅ send_sms、webhook 签名、拆分付款	robokassa.sms、robokassa.webhooks、robokassa.split

环境变量

大多数高级入口点在未显式传入凭据时，会回退使用以下环境变量：

变量	用途
ROBOKASSA_LOGIN	所有操作
ROBOKASSA_PASSWORD1	结账、webhook SuccessURL 验证、CalcOutSumm、财政功能、短信
ROBOKASSA_PASSWORD2	check_payment（OpStateExt）、webhook ResultURL 验证
ROBOKASSA_PASSWORD3	refund_create

签名算法

所有生成签名的辅助函数都接受 algorithm=，可使用 "md5" / "sha256" / "sha384" / "sha512"——请与 Robokassa 控制面板中配置的算法保持一致。

开发

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

许可证

MIT — 请参阅 LICENSE。维护方式为随用随弃；欢迎提交 PR，但不保证会及时审核。