@lk-pay/payhere-mcp

A Model Context Protocol server for PayHere — Sri Lanka's payment gateway.

Lets developers retrieve payments, issue refunds, generate checkout payloads, and compute / verify PayHere signatures directly from Claude Code, Claude Desktop, or any other MCP-aware client.

Status

v0.1 — early preview. Signature module is fully implemented and tested. API-backed tools (get_payment, issue_refund, verify_credentials) ship next.

Related MCP server: PayFast MCP

Install

# Use directly via npx (no install needed)
npx @lk-pay/payhere-mcp

# Or install globally
npm install -g @lk-pay/payhere-mcp

Configure

Set the following environment variables. Copy .env.example to .env for local use, or pass them via your MCP client's config block.

Claude Code setup

Add to your ~/.claude/mcp.json (or project-local .claude/mcp.json):

{
  "mcpServers": {
    "payhere": {
      "command": "npx",
      "args": ["-y", "@lk-pay/payhere-mcp"],
      "env": {
        "PAYHERE_MODE": "sandbox",
        "PAYHERE_MERCHANT_ID": "YOUR_MERCHANT_ID",
        "PAYHERE_MERCHANT_SECRET": "YOUR_MERCHANT_SECRET",
        "PAYHERE_APP_ID": "YOUR_APP_ID",
        "PAYHERE_APP_SECRET": "YOUR_APP_SECRET"
      }
    }
  }
}

Tools

Design notes

• No list_payments. PayHere's Retrieval API only accepts order_id — there is no date-range / status filter endpoint. get_payment returns the array of attempts for an order.

• generate_signature is the differentiator. Most PayHere integration bugs come from incorrect hash computation. This tool exposes the exact algorithm used by the gateway, with constant-time verification for notify URL validation.

• stdio transport only in v0.1. Remote / HTTP transport is on the roadmap.

Development

git clone https://github.com/lakshitha0526/payhere-mcp.git
cd payhere-mcp
npm install

npm run test       # vitest
npm run typecheck  # tsc --noEmit
npm run lint       # biome check
npm run build      # tsup

License

MIT — see LICENSE.

Part of the lk-* family of Sri Lanka-focused developer tooling.