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.

---

Table of contents

• 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.