upi-mcp

A Model Context Protocol (MCP) server for India's UPI. It gives AI assistants (Claude Desktop, Cursor, Cline, the MCP Inspector, etc.) the ability to generate and parse UPI payment links and QR codes — entirely offline, with no API keys and no network calls.

Plenty of web-based UPI QR generators exist. This is the agent-callable form factor: an LLM can mint a upi://pay link or a scannable QR mid-conversation, then validate or parse one. It pairs naturally with payment-API MCP servers.

✨ Features

• 🔗 Generate validated upi://pay deep links from payee details
• 🔳 Generate scannable PNG QR codes — built locally, no external service
• 🔍 Parse a UPI link back into structured fields
• 🛡️ Input validation (VPA format, amount limits)
• 🔒 Zero auth, zero network — pure, deterministic logic
• ⌨️ Written in TypeScript with strict mode

🛠️ Tools

| Tool | Description | |------|-------------| | create_upi_link | Build a validated upi://pay deep link from payee details. Returns the link as text. | | create_upi_qr | Build a UPI link and return it as a scannable PNG QR code (plus the raw link). | | parse_upi_link | Parse a upi://pay link back into structured fields. |

Inputs

create_upi_link / create_upi_qr

| Field | Type | Required | Notes | |-------|------|----------|-------| | payee_vpa | string | ✅ | UPI ID / VPA, e.g. name@okhdfc | | payee_name | string | ✅ | Name shown in the UPI app | | amount | number | ❌ | Fixed amount in INR (must be > 0 and ≤ 1,00,000) | | note | string | ❌ | Short transaction note | | transaction_ref | string | ❌ | Reference id |

parse_upi_link

| Field | Type | Required | |-------|------|----------| | link | string | ✅ |

📋 Requirements

• Node.js 18+ (developed on Node 22)

🚀 Install & build

git clone https://github.com/<your-username>/upi-mcp.git
cd upi-mcp
npm install
npm run build      # compiles TypeScript -> dist/

▶️ Run

npm start          # boots the server on stdio

You should see upi-mcp running on stdio — it then waits for an MCP client to connect.

🧪 Test it (MCP Inspector)

The fastest way to try the tools, no client setup needed:

npx @modelcontextprotocol/inspector node dist/index.js

This opens a local web UI → Connect → Tools tab → List Tools → pick a tool, fill the inputs, and Run. The QR image renders right there.

🖥️ Use with Claude Desktop

Open Settings → Developer → Edit Config and add this (merge into any existing config):

{
  "mcpServers": {
    "upi": {
      "command": "node",
      "args": ["/absolute/path/to/upi-mcp/dist/index.js"]
    }
  }
}

Replace the path with your project's full path + /dist/index.js. Then fully quit Claude Desktop (Cmd + Q) and reopen.

Try: "Make a UPI payment link to pay nirav@okhdfc ₹250 with note test."

⚠️ Note on QR images in Claude Desktop: the desktop client currently has limited/inconsistent support for rendering images returned by MCP tools (and a ~1 MB content cap). The text link always works and is tappable on mobile. To see the QR image reliably, use the MCP Inspector (above), which renders it correctly.

📦 UPI link format

upi://pay?pa=<vpa>&pn=<name>&cu=INR&am=<amount>&tn=<note>&tr=<ref>

Example output

Input: { "payee_vpa": "nirav@okhdfc", "payee_name": "Nirav", "amount": 250, "note": "test" }

upi://pay?pa=nirav%40okhdfc&pn=Nirav&cu=INR&am=250.00&tn=test

parse_upi_link reverses this into { payeeVpa, payeeName, amount, note, transactionRef }.

🧑‍💻 Development

npx tsc --watch    # auto-rebuild on save

Project structure

src/
  upi.ts      # pure logic: build & parse links (no MCP, fully testable)
  index.ts    # the MCP server: wraps the logic as 3 tools over stdio

🌍 Publishing to npm

npm run build
npm publish --access public

Make sure package.json includes "files": ["dist"] so the compiled code ships. Once published, anyone can run it with no clone:

{ "command": "npx", "args": ["-y", "upi-mcp"] }

⚠️ Disclaimer

• UPI supports INR only (cu=INR) and one-time payments via this link format.
• This project is not affiliated with NPCI or any bank. It only constructs the public UPI deep-link URI format and a QR image of it.
• Always verify the payee name in your UPI app before paying.

📄 License

MIT