revolut-merchant-mcp

A Model Context Protocol (MCP) server for the Revolut Merchant API — letting MCP-aware AI assistants (Claude Desktop, Cursor, agent harnesses) read and manage Revolut customers, payment methods, orders, subscriptions, plans, and webhooks.

Why this exists. The existing community Revolut MCP wraps the Revolut Business API (accounts, balances, transfers). This server targets the Merchant API — the surface you use to accept payments and run subscriptions — which had no MCP server until now.

Status: alpha / proof-of-concept. Sandbox-first, read-only by default.

Features

Broad Merchant API coverage across six domains. Read tools are always registered; write (mutating) tools are registered only when REVOLUT_MCP_ALLOW_WRITES=true — so the default posture is read-only.

That's 14 read tools and 21 write tools (35 total).

• Safe defaults: sandbox unless you explicitly opt into production; writes disabled unless explicitly enabled; idempotency keys + transient-error retry in the transport layer.

Related MCP server: Recharge Storefront API MCP Server

Install

# with uv (recommended)
uv pip install -e ".[dev]"

# or pip
pip install -e ".[dev]"

Configure

Copy .env.example and set your sandbox key:

Sandbox keys come from the Revolut Sandbox Business dashboard (Merchant API).

Run

REVOLUT_MERCHANT_SECRET_KEY=sk_sandbox_... revolut-merchant-mcp

The server speaks MCP over stdio.

Claude Desktop / Cursor

{
  "mcpServers": {
    "revolut-merchant": {
      "command": "revolut-merchant-mcp",
      "env": {
        "REVOLUT_MERCHANT_SECRET_KEY": "sk_sandbox_...",
        "REVOLUT_SANDBOX": "true"
      }
    }
  }
}

Architecture

config.py        env → Config (sandbox/prod guard, write gate)
client.py        async transport: auth, versioning, idempotency, retry, errors
operations/      one module per domain (customers, orders, subscriptions,
                 plans, webhooks); each holds framework-free async fns plus a
                 register(mcp, client, allow_writes, safe) that wires its tools
server.py        FastMCP wrapper — iterates the domain registrars (writes gated)

The pure functions in operations/ have no MCP dependency, so the API layer is fully testable with respx and reusable outside the server. Payment methods are customer-nested (/customers/{id}/payment-methods) and so live in the customers module.

Develop

ruff check .
pytest

Tests mock the Revolut sandbox host with respx — no live keys, no network.

Safety notes

• This server can mutate live data (customers, payment methods, orders, subscriptions, plans, and webhooks — including refunds and order capture) when writes are enabled against a production key. Production and writes are both off by default and each requires an explicit opt-in.

• Treat your Merchant secret like any payment credential. Prefer a sandbox key for anything agent-driven.

License

MIT © Sherman Studio Ltd. Not affiliated with or endorsed by Revolut.