Skip to main content
Glama
mcp-jazzcash

mcp-jazzcash

by TehreemArbab

mcp-jazzcash

npm version License: MIT Node MCP Status

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


Related MCP server: Juspay MCP Tools

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.

Available Tools

5 tools
jazzcash_charge_mobile_walletCharge JazzCash Mobile Wallet (MWALLET)C

Server-to-server charge against a JazzCash mobile wallet. Customer authorizes via MPIN on their phone. Amount is in PKR paisa.

Inputs: amount_paisa (required), description (required), bill_reference (required), mobile_number (required), +7 more.

jazzcash_create_hosted_checkoutCreate JazzCash Hosted CheckoutA

Build a signed Hosted Checkout (Page Redirection) form that redirects the customer to JazzCash to pay. Returns the action URL, hidden fields, and a ready-to-use HTML form snippet. Amount is in PKR paisa (rupees * 100).

Inputs: amount_paisa (required), description (required), bill_reference (required), txn_ref_no, +6 more.

jazzcash_environment_infoShow current JazzCash environmentA

Returns the active environment (sandbox/production), endpoint URLs in use, and whether credentials are configured. Does not return secrets.

Inputs: no named parameters.

jazzcash_inquire_transactionInquire JazzCash transaction statusB

Look up the current status of a JazzCash transaction by its pp_TxnRefNo.

Inputs: txn_ref_no (required).

jazzcash_refund_transactionRefund a JazzCash transactionB

Issue a full or partial refund against a previously settled JazzCash transaction. Requires the merchant account to have refund permissions enabled.

Inputs: txn_ref_no (required), amount_paisa (required), description (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct operation: charging mobile wallet, creating hosted checkout, environment info, inquiring transactions, and refunding. No overlap in functionality.

    Naming Consistency4/5

    All names use snake_case with a consistent 'jazzcash_' prefix. Most follow a verb_noun pattern (charge_mobile_wallet, create_hosted_checkout, inquire_transaction, refund_transaction), though 'environment_info' is noun_noun, which is a minor deviation.

    Tool Count5/5

    Five tools cover the core operations for a payment gateway integration: charge, checkout, inquiry, refund, and environment check. This is well-scoped for the stated domain.

    Completeness4/5

    The tool surface covers essential payment lifecycle operations: creating charges, checkout flows, status inquiry, and refunds. Missing features like void/cancel or webhook verification are minor gaps for a basic integration.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to interact with multiple payment providers (Stripe, Paystack) through a unified API. Supports payment initialization, verification, refunds, customer management, and invoicing without requiring knowledge of specific provider implementations.
      2
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to interact with Juspay's payment processing APIs and merchant dashboard for managing orders, transactions, refunds, customers, gateways, and reporting through natural language.
      22
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to access Magpie Payment Platform APIs for processing payments, creating checkout sessions, sending invoices, and managing payment links through natural conversation.
      95 npm
      2
      MIT