mcp-jazzcash

An open-source Model Context Protocol server for JazzCash — Pakistan's largest mobile-money platform. Plug it into Claude Desktop, Cursor, Cline, or any MCP-aware agent and let it create checkouts, charge mobile wallets, look up transactions, and issue refunds against the JazzCash REST API.

Sandbox-by-default. Bring your own merchant credentials. No secrets bundled.

Why this exists
Tools
Quick start
Configuration
Wire it into Claude Desktop
Use it from any MCP client
How the signature works
Endpoint overrides
Security model
Roadmap
Contributing
License

Why this exists

The Pakistani payments stack is fragmented and English-language documentation for AI agents is thin. This MCP gives any agent a stable, typed interface to JazzCash so you don't have to teach it the signature scheme, field names, and gotchas every time. Prompt your agent in plain English; let the server do the cryptography and HTTP.

Tools

| Tool | Purpose | |---|---| | jazzcash_create_hosted_checkout | Builds a signed Hosted Checkout (Page Redirection) form. Returns the action URL, hidden fields, and a ready-to-use HTML snippet your app can serve. | | jazzcash_charge_mobile_wallet | Server-to-server MWALLET charge. Customer authorizes via MPIN on their phone. | | jazzcash_inquire_transaction | Status lookup by pp_TxnRefNo. | | jazzcash_refund_transaction | Full or partial refund (requires merchant role). | | jazzcash_environment_info | Reports active environment, endpoint URLs, and which credentials are present. Never returns secrets. |

All amounts are passed as PKR paisa (rupees × 100) to avoid float rounding.

Quick start

git clone https://github.com/TehreemArbab/JazzCashMCP.git
cd JazzCashMCP
npm install
cp .env.example .env       # then edit .env with your sandbox credentials
npm run build
npm start

The server speaks MCP over stdio, so npm start is most useful when launched by an MCP client (see below). To verify the build alone:

npm run typecheck

Configuration

Copy .env.example to .env and fill in credentials from your JazzCash merchant portal:

JAZZCASH_MERCHANT_ID=MC...
JAZZCASH_PASSWORD=...
JAZZCASH_INTEGRITY_SALT=...
JAZZCASH_ENV=sandbox
JAZZCASH_RETURN_URL=https://yourapp.example.com/jazzcash/callback

Sandbox credentials are issued at https://sandbox.jazzcash.com.pk. To go live, switch JAZZCASH_ENV=production and swap in your live merchant credentials — no code changes required.

| Variable | Required | Notes | |---|---|---| | JAZZCASH_MERCHANT_ID | yes | From the merchant portal. | | JAZZCASH_PASSWORD | yes | API password, not your portal login. | | JAZZCASH_INTEGRITY_SALT | yes | HMAC key for pp_SecureHash. | | JAZZCASH_ENV | yes | sandbox or production. | | JAZZCASH_RETURN_URL | only for hosted checkout | Where JazzCash redirects the customer post-payment. | | JAZZCASH_LANGUAGE | no | Default EN. | | JAZZCASH_CURRENCY | no | Default PKR. | | JAZZCASH_VERSION | no | Default 1.1. | | JAZZCASH_*_URL | no | Per-endpoint URL override; see Endpoint overrides. |

Wire it into Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "jazzcash": {
      "command": "node",
      "args": ["C:/path/to/mcp-jazzcash/dist/index.js"],
      "env": {
        "JAZZCASH_MERCHANT_ID": "MC...",
        "JAZZCASH_PASSWORD": "...",
        "JAZZCASH_INTEGRITY_SALT": "...",
        "JAZZCASH_ENV": "sandbox",
        "JAZZCASH_RETURN_URL": "https://yourapp.example.com/jazzcash/callback"
      }
    }
  }
}

Restart Claude Desktop, then try:

"Using the JazzCash MCP, create a hosted checkout for PKR 1500 with description 'Order #1023' and bill reference 'INV1023'."

Claude will call jazzcash_create_hosted_checkout and hand back the form HTML.

Use it from any MCP client

The server uses stdio transport, so it works with anything that speaks MCP — Cursor, Cline, Continue, Zed, and custom agents built on the MCP TypeScript SDK. Point the client at node /path/to/dist/index.js and pass the same env vars shown above.

How the signature works

JazzCash uses HMAC-SHA256 over alphabetically sorted, non-empty pp_* fields, joined with &, with the merchant's Integrity Salt as both the HMAC key and a prepended salt:

message = integritySalt + "&" + sortedField1Value + "&" + sortedField2Value + ...
hash    = hex(HMAC_SHA256(key=integritySalt, message))

pp_SecureHash itself is excluded from the message. Empty values are skipped. The implementation lives in src/signature.ts — small enough to audit in 30 seconds.

Endpoint overrides

Default endpoint URLs ship for both sandbox and production. If JazzCash rotates a path, override the relevant variable without changing code:

JAZZCASH_HOSTED_CHECKOUT_URL=https://sandbox.jazzcash.com.pk/.../HostedCheckout
JAZZCASH_MOBILE_WALLET_URL=https://sandbox.jazzcash.com.pk/.../DoMWalletTransaction
JAZZCASH_INQUIRY_URL=https://sandbox.jazzcash.com.pk/.../StatusInquiry
JAZZCASH_REFUND_URL=https://sandbox.jazzcash.com.pk/.../DoRefundTransaction

Security model

No bundled secrets. Credentials are read from environment variables only.
No secrets in tool output. jazzcash_environment_info returns only booleans for which credentials are configured.
Sandbox is the default. Production requires explicitly setting JAZZCASH_ENV=production.
Stdio transport. The server has no network listener; it talks only to the parent MCP client process.
Audit-friendly. Signature logic is isolated in one short file. No vendored crypto.

If you find a security issue, please open a private advisory on GitHub rather than a public issue.

Roadmap

[ ] Card / Tokenization tools (Authorize, Capture, Retrieve/Delete Token)
[ ] IPN webhook signature-verification helper
[ ] Voucher / OTC payment flow
[ ] CLI (mcp-jazzcash inspect) for hash debugging
[ ] Published npm package + automated releases

Contributing

Issues and PRs welcome. A few ground rules:

Don't paste real merchant credentials into bug reports — use the placeholder JAZZCASH_* names.
Keep new tools framework-agnostic; the server should remain usable from any MCP client.
Run npm run typecheck before opening a PR.

License

MIT. Not affiliated with or endorsed by JazzCash, Mobilink Microfinance Bank, or VEON.

MCP Servers