daraja-mcp

An MCP server for the Safaricom M-Pesa Daraja 3.0 API.

Covers the full product surface including M-Pesa Ratiba, verifies the source of inbound callbacks, and ships a simulator so you can run every tool without a Safaricom account.

npx daraja-mcp

That works on a machine that has never heard of Safaricom. No credentials, no sandbox app, no tunnel. It starts a local fake Daraja and points the server at it, so you can call stk_push_and_wait and watch a payment settle end to end before you decide whether this is worth your time.

Why another one

There are several M-Pesa MCP servers already. Most wrap POST /stkpush and stop. The three things that make Daraja genuinely hard to work with are:

The result does not come back in the response. You initiate a payment, get an acknowledgement, and the actual outcome arrives on a webhook up to a minute later. A tool that returns the acknowledgement has told the model nothing. So this server runs a callback receiver and offers *_and_wait tools that block until the real outcome arrives and return the receipt number.

Callbacks are unsigned. Safaricom does not sign callback bodies. The only thing distinguishing a genuine payment result from a forged one is the source address, which means an open callback endpoint lets anyone mark an unpaid order as paid. This server verifies inbound callbacks against Safaricom's published egress ranges, supports an unguessable path secret, and refuses to disable verification in production.

You cannot test any of it without an account. Daraja requires credentials and a publicly reachable HTTPS callback URL before the first request works. The bundled simulator speaks the real endpoint paths, returns the real payload shapes, and pushes callbacks the way Safaricom does, so the test suite runs in CI with no secrets and you can evaluate the server in under a minute.

Install

Add to your MCP client config:

{
  "mcpServers": {
    "daraja": {
      "command": "npx",
      "args": ["-y", "daraja-mcp"]
    }
  }
}

That runs in simulator mode. To talk to the real sandbox, add credentials:

{
  "mcpServers": {
    "daraja": {
      "command": "npx",
      "args": ["-y", "daraja-mcp"],
      "env": {
        "DARAJA_CONSUMER_KEY": "your-key",
        "DARAJA_CONSUMER_SECRET": "your-secret",
        "DARAJA_SHORTCODE": "174379",
        "DARAJA_PASSKEY": "your-passkey",
        "DARAJA_CALLBACK_PUBLIC_URL": "https://your-tunnel.ngrok.io"
      }
    }
  }
}

Client-specific instructions: docs/clients.md.

Tools

Payments

Tool	What it does
stk_push	Send a payment prompt. Returns an acknowledgement only.
stk_push_and_wait	Send a prompt and wait for the customer. Returns the receipt.
stk_query	Check the status of a previous prompt.
ratiba_create	Create a standing order for recurring collection.
ratiba_create_and_wait	Create one and wait for the customer to approve.
generate_qr	Generate a dynamic QR code.

Disbursement

Tool	What it does
b2c_payment	Pay a customer: refunds, withdrawals, salaries.
b2c_payment_and_wait	Same, but returns the settled result.
b2b_payment	Pay a PayBill, a till, or top up a B2C working account.
tax_remittance	Remit tax to KRA against a PRN.
business_to_pochi	Pay a Pochi la Biashara number.

Treasury

Tool	What it does
account_balance	Query your business account balance.
transaction_status	Look up any past transaction.
reversal	Reverse a transaction paid into your shortcode.

Customer to business

Tool	What it does
c2b_register_urls	Register validation and confirmation URLs.
c2b_simulate	Simulate a customer payment. Sandbox only.
pull_register	Register for the Pull Transactions API.
pull_transactions	Fetch C2B transactions for a window.

Identity and fraud (new in Daraja 3.0)

Tool	What it does
check_sim_swap	When was this number last SIM-swapped?
check_age_on_network	When was this number first registered?
validate_identity	Is this number registered to this national ID?
query_org_info	What business owns this shortcode, and at what tariff?

Those four are worth more than they look. Checking for a recent SIM swap before disbursing to an unfamiliar number is a cheap control against SIM-swap fraud, and query_org_info catches a fat-fingered shortcode before the money leaves.

Diagnostics

Tool	What it does
list_callbacks	Recent callbacks, newest first.
get_callback	Full payload for a correlation id.
server_health	Mode, configured credentials, receiver status.

Start with server_health when something is not working.

Testing without a Safaricom account

Simulator mode is the default when no credentials are set. Failure paths are driven by the amount, so you can exercise every branch deterministically:

Amount	What happens
anything normal	Success, with a receipt number
1	Insufficient funds
1032	Cancelled by user
1037	Timeout, customer unreachable
2001	Wrong PIN
9999	Upstream 500, to exercise retry handling

So stk_push_and_wait with amount 1032 gives you a realistic cancelled payment, including the detail that failure callbacks carry no CallbackMetadata at all. Code that reads the receipt number unconditionally breaks there, which is exactly what you want to find locally.

Going live

Read docs/going-live.md before pointing this at production. The short version:

1. Set DARAJA_MODE=production and real credentials.
2. Set DARAJA_CALLBACK_PUBLIC_URL to a public HTTPS endpoint.
3. Leave source verification on. It is on by default and the server refuses to let you disable it in production.
4. Set DARAJA_CALLBACK_PATH_SECRET to a random string.

Ratiba additionally requires a signed commercial agreement with Safaricom before it works outside the sandbox.

Configuration

Variable	Purpose
DARAJA_MODE	simulator, sandbox, or production
DARAJA_CONSUMER_KEY	From your Daraja app
DARAJA_CONSUMER_SECRET	From your Daraja app
DARAJA_SHORTCODE	PayBill or till number
DARAJA_PASSKEY	Lipa na M-Pesa passkey, for STK push
DARAJA_INITIATOR_NAME	For B2C, B2B, reversals, balance
DARAJA_SECURITY_CREDENTIAL	Encrypted initiator password
DARAJA_CALLBACK_PUBLIC_URL	Public URL Safaricom can reach
DARAJA_CALLBACK_PORT	Local listener port, default 8787
DARAJA_CALLBACK_PATH_SECRET	Unguessable path segment
DARAJA_CALLBACK_CIDRS	Override allowed source ranges
DARAJA_DISABLE_RECEIVER	Skip the callback listener entirely

Notes on Daraja's own inconsistencies

These are reproduced deliberately rather than tidied up, because Daraja rejects the corrected forms:

• B2C sends InitiatorName; B2B and the treasury APIs send Initiator.
• RecieverIdentifierType is misspelled in the specification.
• B2C expects Occassion; transaction status expects Occasion.
• Ratiba's published sample says StandingOrderNameName while its parameter table says StandingOrderName. Both are sent.
• Ratiba's synchronous response uses ResponseHeader and code 200; its callback uses responseHeader and code 0. Different casing, different code space, same product.
• STK ResultCode is numeric; most other products send it as a string.

The timestamp is rendered in East Africa Time rather than UTC. Using UTC backdates the request by three hours and Daraja rejects it as expired, which is the single most common STK push bug.

Using the pieces directly

The client, simulator, and callback receiver are exported independently if you want them without MCP:

import { DarajaClient, DarajaSimulator, loadConfig } from 'daraja-mcp';

Development

npm install
npm test              # 507 tests, no credentials needed
npm run test:coverage # with a coverage report
npm run build
npm run verify        # typecheck, test, build, and an end-to-end MCP check

npm run verify is the full gate. It drives the built CLI over stdio MCP through a payment, a cancellation, and a standing order against the simulator, so it needs no Safaricom credentials.

Coverage sits at about 98% of lines, with thresholds enforced by the test run so a regression fails rather than passing quietly. The badge is generated locally with npm run coverage:badge, since this repository does not run CI.

The docs site is served from the gh-pages branch. To update it, edit site/index.html on main and run npm run docs:publish.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for how to get set up and what makes a change likely to be merged.

The most useful thing you can report is a Daraja discrepancy: a case where the real API behaves differently from what this server assumes. Those are the ones the simulator cannot catch on its own. There is an issue template for it.

Everything here derives from Safaricom's public documentation. Please do not contribute code or payloads taken from an employer's or client's private integration.

Security

Callbacks are unsigned, so a forged one that gets accepted is a real vulnerability. Report privately rather than in a public issue: see SECURITY.md.

Disclaimer

Not affiliated with or endorsed by Safaricom PLC. M-PESA and Daraja are their trademarks. Built from the public Daraja documentation.

License

MIT