CL Razorpay MCP Server

Interact with Razorpay's payment infrastructure — orders, payments, refunds, and settlements — via API.

A Model Context Protocol (MCP) server that exposes Razorpay's REST API for managing orders, capturing payments, processing refunds, and querying settlements.

Overview

The CL Razorpay MCP Server provides stateless, multi-tenant access to the Razorpay API:

• Order management — create, fetch, update, and list orders

• Payment operations — fetch, capture, and update payments

• Refund handling — issue full or partial refunds, query refund status

• Settlement queries — list and inspect settlement records

Perfect for:

• Automating payment operations from AI agents or internal tools

• Querying transaction history and settlement data programmatically

• Building Claude-powered finance dashboards or customer support bots

Authentication

This server is stateless and multi-tenant. Every tenant-facing tool accepts key_id and key_secret on each call. Credentials are never stored server-side.

Obtain your API keys from the Razorpay Dashboard:

1. Log in to your Razorpay Dashboard.

2. Navigate to Settings → API Keys.

3. Click Generate Test Key (for sandbox) or Generate Live Key.

4. Copy the Key ID and Key Secret — the secret is shown only once.

Use the test-mode keys against https://api.razorpay.com/v1 — Razorpay's sandbox is live mode with test credentials, no separate base URL needed.

Tools

Lightweight ping that confirms the MCP server is live. No auth required.

Inputs: none

Output:

{ "status": "ok", "server": "CL Razorpay MCP Server" }

Orders

Creates an order that is required before initiating a payment on the frontend SDK.

Inputs:

• key_id (string, required) — Razorpay API key ID

• key_secret (string, required) — Razorpay API key secret

• amount (integer, required) — Amount in smallest currency unit (e.g. paise for INR; ₹500 = 50000)

• currency (string, required) — ISO 4217 currency code, e.g. "INR"

• receipt (string, optional) — Merchant receipt number (max 40 chars)

• notes (object, optional) — Key-value metadata to attach

• partial_payment (boolean, optional) — Whether partial payments are allowed (default: false)

Output:

{
  "id": "order_XXXXXXXXXX",
  "entity": "order",
  "amount": 50000,
  "currency": "INR",
  "status": "created",
  "receipt": "receipt_001",
  "created_at": 1690000000
}

Usage Example:

POST /mcp/razorpay/create_order

{
  "key_id": "rzp_test_XXXXXXXX",
  "key_secret": "XXXXXXXXXXXXXXXX",
  "amount": 50000,
  "currency": "INR",
  "receipt": "receipt_001"
}

Retrieves full details of a specific order.

Inputs:

• key_id (string, required)

• key_secret (string, required)

• order_id (string, required) — e.g. "order_XXXXXXXXXX"

Output: Full order object as returned by Razorpay API.

Retrieves a paginated list of orders, optionally filtered by creation timestamp.

Inputs:

• key_id (string, required)

• key_secret (string, required)

• count (integer, optional) — Number to return (default: 10, max: 100)

• skip (integer, optional) — Offset for pagination (default: 0)

• from_timestamp (integer, optional) — Unix epoch; fetch orders created after this

• to_timestamp (integer, optional) — Unix epoch; fetch orders created before this

Retrieves all payment attempts made against a specific order ID.

Inputs:

• key_id (string, required)

• key_secret (string, required)

• order_id (string, required) — e.g. "order_XXXXXXXXXX"

Updates the notes key-value map on an existing order.

Inputs:

• key_id (string, required)

• key_secret (string, required)

• order_id (string, required)

• notes (object, required) — Key-value pairs to set

Payments

Retrieves details of a specific payment.

Inputs:

• key_id (string, required)

• key_secret (string, required)

• payment_id (string, required) — e.g. "pay_XXXXXXXXXX"

Retrieves a paginated list of payments with optional timestamp filters.

Inputs:

• key_id (string, required)

• key_secret (string, required)

• count (integer, optional) — default 10, max 100

• skip (integer, optional) — default 0

• from_timestamp (integer, optional)

• to_timestamp (integer, optional)

Changes a payment from authorized to captured. Amount must exactly match the authorized amount.

Inputs:

• key_id (string, required)

• key_secret (string, required)

• payment_id (string, required) — e.g. "pay_XXXXXXXXXX"

• amount (integer, required) — Must match the authorized amount exactly

• currency (string, required) — e.g. "INR"

Updates the notes key-value map on an existing payment.

Inputs:

• key_id (string, required)

• key_secret (string, required)

• payment_id (string, required)

• notes (object, required)

Refunds

Creates a refund for a captured payment. Omit amount for a full refund.

Inputs:

• key_id (string, required)

• key_secret (string, required)

• payment_id (string, required) — e.g. "pay_XXXXXXXXXX"

• amount (integer, optional) — Partial refund amount; omit for full refund

• speed (string, optional) — "normal" (default) or "optimum"

• notes (object, optional) — Key-value metadata

• receipt (string, optional) — Merchant receipt for the refund

Output:

{
  "id": "rfnd_XXXXXXXXXX",
  "entity": "refund",
  "amount": 50000,
  "payment_id": "pay_XXXXXXXXXX",
  "speed_processed": "normal",
  "status": "processed"
}

Inputs:

• key_id (string, required)

• key_secret (string, required)

• refund_id (string, required) — e.g. "rfnd_XXXXXXXXXX"

Inputs:

• key_id (string, required)

• key_secret (string, required)

• count (integer, optional) — default 10, max 100

• skip (integer, optional) — default 0

• from_timestamp (integer, optional)

• to_timestamp (integer, optional)

Inputs:

• key_id (string, required)

• key_secret (string, required)

• payment_id (string, required) — e.g. "pay_XXXXXXXXXX"

• count (integer, optional) — default 10

• skip (integer, optional) — default 0

Inputs:

• key_id (string, required)

• key_secret (string, required)

• refund_id (string, required)

• notes (object, required)

Settlements

Inputs:

• key_id (string, required)

• key_secret (string, required)

• count (integer, optional) — default 10, max 100

• skip (integer, optional) — default 0

• from_timestamp (integer, optional)

• to_timestamp (integer, optional)

Inputs:

• key_id (string, required)

• key_secret (string, required)

• settlement_id (string, required) — e.g. "setl_XXXXXXXXXX"

Common Parameters

• count — Number of records to return (integer, 1–100, default 10)

• skip — Number of records to skip for pagination (integer, default 0)

• from_timestamp — Unix epoch integer; lower bound on created_at

• to_timestamp — Unix epoch integer; upper bound on created_at

Resource ID Formats

Order:

order_{alphanumeric}
Example: order_OE1jIbY9HrFaXw

Payment:

pay_{alphanumeric}
Example: pay_OE1jIbY9HrFaXw

Refund:

rfnd_{alphanumeric}
Example: rfnd_OE1jIbY9HrFaXw

Settlement:

setl_{alphanumeric}
Example: setl_OE1jIbY9HrFaXw

All tools require Razorpay API credentials. Here's how to obtain them:

Step 1: Sign Up / Log In

1. Go to Razorpay Dashboard

2. Sign up or log into your account

Step 2: Generate API Keys

1. Navigate to Settings → API Keys

2. Click Generate Test Key for sandbox or Regenerate Live Key for production

3. Download or copy both Key ID and Key Secret immediately

Step 3: Use Credentials Per Request

Pass key_id and key_secret in every tool call. The server uses HTTP Basic Auth (key_id as username, key_secret as password) on each request.

Step 4: Required Permissions

Ensure your Razorpay account has:

• payments:read — Read payment details

• payments:write — Capture and update payments

• orders:read — Read order details

• orders:write — Create and update orders

• refunds:read — Read refund details

• refunds:write — Create and update refunds

• settlements:read — Read settlement details

Refer to the Razorpay Authentication Guide for details.

Missing or Invalid API Key

• Cause: key_id or key_secret is missing, incorrect, or belongs to a different mode (test vs live)

• Solution:

  1. Re-copy credentials from the Razorpay Dashboard

  2. Ensure you are using test keys for sandbox and live keys for production

  3. Regenerate keys if they have been rotated

Insufficient Credits / Rate Limiting

• Cause: API calls have exceeded your account's rate limits

• Solution:

  1. Reduce request frequency

  2. Check Razorpay API Best Practices for rate limit guidance

Malformed Request Payload

• Cause: Required fields missing or wrong types

• Solution:

  1. Ensure amount is an integer in smallest currency unit (paise, not rupees)

  2. Ensure all required tool parameters are provided

  3. Verify currency is a valid ISO 4217 code

Payment Cannot Be Captured

• Cause: Payment is not in authorized state, or amount mismatch

• Solution:

  1. Check payment status with fetch_payment before capturing

  2. Ensure amount in capture_payment exactly matches the authorized amount

Refund Cannot Be Created

• Cause: Payment is not in captured state, or has already been fully refunded

• Solution:

  1. Verify payment status with fetch_payment

  2. Check existing refunds with fetch_refunds_for_payment

• Razorpay API Documentation — Official API reference

• Razorpay Authentication Guide — Auth setup guide

• Razorpay Orders API — Orders endpoint reference

• Razorpay Payments API — Payments endpoint reference

• Razorpay Refunds API — Refunds endpoint reference

• Razorpay Settlements API — Settlements endpoint reference

• FastMCP Docs — FastMCP specification

Setup

pip install -r requirements.txt

Running the Server

# stdio (default — for local Claude Desktop / MCP clients)
python server.py

# SSE transport
python server.py --transport sse --host 127.0.0.1 --port 8001

# Streamable HTTP transport
python server.py --transport streamable-http --host 127.0.0.1 --port 8001

Example Tool Call

{
  "tool": "create_order",
  "arguments": {
    "key_id": "rzp_test_XXXXXXXX",
    "key_secret": "XXXXXXXXXXXXXXXX",
    "amount": 50000,
    "currency": "INR",
    "receipt": "receipt_001"
  }
}

Project Structure

cl-mcp-razorpay/
|-- server.py
|-- requirements.txt
|-- README.md
|-- .gitignore
`-- razorpay_mcp/
    |-- __init__.py
    |-- cli.py
    |-- config.py
    |-- schemas.py
    |-- service.py
    `-- tools.py