Robokassa Mcp

robokassa-mcp

📚 ドキュメント  ·  PyPI  ·  Docker  ·  MCP レジストリ

---

Robokassa（ロシアの決済ゲートウェイ）向けの包括的な Python クライアントおよび Model Context Protocol サーバーです。

チェックアウト、XML ステータスインターフェース、返金、ホールディング（事前承認）、定期サブスクリプション、54-ФЗ の税務レシート、Partner API、補助エンドポイントなど、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。

エージェントに公開される MCP ツール

18 個のツールはすべて @mcp.tool() でラップされており、MCP 対応の任意のエージェント（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	2 段階のカード事前承認です。	Password#1
init_recurring_parent / recurring_charge	サブスクリプションの自動課金です。	Password#1
build_split_invoice	マーケットプレイス向けの複数受取人チェックアウトです。	—
send_sms	有料 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 グループとの対応状況：

グループ	対応状況	モジュール
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	✅ 親 + 子	robokassa.recurring
Fiscal 54-ФЗ	✅ 2 回目のレシートの作成 / 状態確認	robokassa.fiscal
Partner API	🟡 partner_refund のみ — 対応状況のメモを参照	robokassa.partner
Auxiliary	✅ send_sms、Webhook 署名、分割払い	robokassa.sms、robokassa.webhooks、robokassa.split

環境変数

認証情報が明示的に渡されない場合、ほとんどの高レベルのエントリーポイントでは、以下の環境変数が使用されます。

変数	必要な操作
ROBOKASSA_LOGIN	すべての操作
ROBOKASSA_PASSWORD1	チェックアウト、Webhook の SuccessURL 検証、CalcOutSumm、税務関連、SMS
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 は歓迎しますが、速やかにレビューされるとは限りません。