Revolut Business MCP

Read-only Model Context Protocol (MCP) server exposing Revolut Business transaction data to MCP clients over stdio.

Tools

revolut_list_transactions

List transactions. Single-page passthrough of the Revolut API response; no lossy field mapping.

Parameter	Type	Notes
from	string (ISO calendar date or RFC3339 datetime)	optional
to	string (ISO calendar date or RFC3339 datetime)	optional
account	string (UUID)	optional, filter by account
count	integer 1–1000	optional
type	enum	optional; one of atm, card_payment, card_refund, card_chargeback, card_credit, charge, charge_refund, exchange, transfer, loan, fee, refund, topup, topup_return, tax, tax_refund

revolut_get_transaction

Get a single transaction.

Parameter	Type	Notes
id	string	required
id_type	literal "request_id"	optional; when set, id is treated as a request ID and only resolves transactions created within the last 2 weeks

Pagination caveat

revolut_list_transactions returns one page only, matching the Revolut API's own behavior. The server does not auto-paginate. Use from/to to page through results yourself.

Prerequisites

• Node.js 22+
• A Revolut Business account with API access
• A client certificate registered with Revolut for API authentication, and the corresponding private key

Follow Revolut's official setup guides before configuring this server:

• Revolut Business API documentation
• Setting up authentication (client credentials / certificate)

Install / build / test

npm install
npm run build       # tsc -> dist/
npm run typecheck    # tsc --noEmit
npm test             # tsx --test test/**/*.test.ts

Environment configuration

Copy .env.example to .env and fill in values. Do not commit .env or any private key material.

.env is auto-loaded (via Node's --env-file-if-exists=.env) only by npm start and npm run dev. Running node dist/src/index.js directly does not load .env; supply the required variables externally (e.g. via your process manager or shell), or invoke Node yourself with --env-file-if-exists=.env.

Variable	Description
REVOLUT_ENV	sandbox (default) or production. Selects the API base URL.
REVOLUT_CLIENT_ID	OAuth client ID from your Revolut Business API app.
REVOLUT_JWT_ISS	JWT iss claim value used when signing the client assertion.
REVOLUT_PRIVATE_KEY	PEM private key matching the certificate registered with Revolut. Supports literal \n line breaks (quoted single-line form), which the server normalises.
REVOLUT_REFRESH_TOKEN	Initial OAuth refresh token obtained via Revolut's authorization flow.
REVOLUT_HTTP_TIMEOUT_MS	Optional. HTTP request timeout in milliseconds, integer between 100 and 120000. Defaults to 15000.

Sandbox vs production

REVOLUT_ENV=sandbox targets https://sandbox-b2b.revolut.com/api/1.0; REVOLUT_ENV=production targets https://b2b.revolut.com/api/1.0. Any other value fails config loading at startup.

Refresh-token behavior

The server exchanges the configured refresh token for a short-lived access token on first use, caches it in memory, and renews it automatically before expiry (60s skew) or on a 401 response. If Revolut rotates the refresh token in its response, the rotated token is adopted only in memory for the current process and is never written to .env or any file. On restart, the server always uses the REVOLUT_REFRESH_TOKEN value from the environment, regardless of any rotation that happened in a previous run. If the old token was invalidated by rotation, the process fails to authenticate until REVOLUT_REFRESH_TOKEN is updated.

Operators who need rotation to survive restarts must build their own secure external persistence (e.g., a secrets manager write-back) and update the environment before the next start. This server does not provide that mechanism.

Running locally (stdio)

npm run build
npm start

npm start runs node --env-file-if-exists=.env dist/src/index.js, which auto-loads .env if present. For development without a build step, npm run dev runs the same via tsx against src/index.ts with the same .env auto-loading.

The server communicates over stdio; it has no HTTP listener. Run it via an MCP client that spawns it as a subprocess. If your MCP client invokes node dist/src/index.js directly (bypassing the npm scripts), it will not auto-load .env; the client must supply the environment variables itself (see the config example below) or you must add --env-file-if-exists=.env to the invocation.

MCP client configuration example

Generic stdio MCP client config (adapt keys to your client's format):

{
  "mcpServers": {
    "revolut-business": {
      "command": "node",
      "args": ["/absolute/path/to/revolut-business-mcp/dist/src/index.js"],
      "env": {
        "REVOLUT_ENV": "sandbox",
        "REVOLUT_CLIENT_ID": "...",
        "REVOLUT_JWT_ISS": "...",
        "REVOLUT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
        "REVOLUT_REFRESH_TOKEN": "..."
      }
    }
  }
}

Security notes

• Never commit .env, private keys, or refresh tokens.
• Treat the refresh token as a long-lived credential; rotate it if leaked.
• The private key must correspond to the certificate registered with Revolut for this API client; keep it out of shell history and logs.
• This server is read-only: it exposes no write, transfer, or payment-initiating tools.

Non-goals (current)

• No auto-pagination across multiple pages of transactions.
• No caching, persistence, or database layer.
• No write/transfer/payment tools — listing and single-transaction retrieval only.
• No transport other than stdio.
• No automated refresh-token persistence back to environment files.

This README does not claim live verification against the production Revolut API; behavior is based on the implemented code and Revolut's published API documentation.