JazzCashMCP

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 71)

Open-source Model Context Protocol (MCP) server for JazzCash — Pakistan's largest mobile-money platform. Hosted Checkout, Mobile Wallet charges, inquiries, and refunds for AI agents.

JazzCashMCP Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# mcp-jazzcash

[![npm version](https://img.shields.io/badge/npm-mcp--jazzcash-cb3837?logo=npm)](https://www.npmjs.com/package/mcp-jazzcash)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/TehreemArbab/JazzCashMCP/main/LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A518.17-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-1.0-7c3aed)](https://modelcontextprotocol.io)
[![Status](https://img.shields.io/badge/status-alpha-orange)]()

An open-source [Model Context Protocol](https://modelcontextprotocol.io) 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](#why-this-exists)
- [Tools](#tools)
- [Quick start](#quick-start)
- [Configuration](#configuration)
- [Wire it into Claude Desktop](#wire-it-into-claude-desktop)
- [Use it from any MCP client](#use-it-from-any-mcp-client)
- [How the signature works](#how-the-signature-works)
- [Endpoint overrides](#endpoint-overrides)
- [Security model](#security-model)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#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

```bash
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:

```bash
npm run typecheck
```

## Configuration

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

```bash
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](#endpoint-overrides). |

## Wire it into Claude Desktop

Add this to `claude_desktop_config.json`:

```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](https://github.com/modelcontextprotocol/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:

```text
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`](./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:

```bash
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](./LICENSE). Not affiliated with or endorsed by JazzCash, Mobilink Microfinance Bank, or VEON.

JazzCashMCP

JazzCashMCP Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

JazzCashMCP

JazzCashMCP Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README