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.