daraja-mcp
An MCP server that gives a model full access to the Safaricom M-Pesa Daraja 3.0 API (all 26 products), with built-in callback handling and a credential-free simulator.
Collect payments: send STK push prompts (
stk_push), or block until the customer pays and get the receipt (stk_push_and_wait), and query past prompts.Recurring billing: create Ratiba standing orders, optionally waiting for customer approval.
QR codes: generate dynamic M-Pesa QR codes for a till, paybill, or phone.
Disburse money: pay customers (B2C), businesses/tills/working-account top-ups (B2B), Pochi la Biashara numbers, and KRA tax via PRN — with
_and_waitvariants that return the settled result.Treasury: check account balance, look up any past transaction, and reverse a payment into your shortcode.
C2B: register validation/confirmation URLs, simulate customer payments (sandbox), register for and fetch Pull Transactions for reconciliation.
Identity & fraud: check SIM-swap recency, line age, phone-to-national-ID match, and confirm a shortcode's registered owner/tariff before paying.
Debug callbacks: list received callbacks, filter by product family, and fetch full payloads by correlation id.
Diagnostics:
server_healthreports mode, configured credentials, and receiver status.Test without an account: simulator mode (default) drives deterministic failure paths by amount (1, 1032, 1037, 2001, 9999) and pushes realistic callbacks.
Callback security: verifies inbound callbacks against Safaricom's egress ranges, supports a path secret, and won't disable verification in production.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@daraja-mcp Send an STK push to 254712345678 for 500 KES and wait for the receipt"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
daraja-mcp
An MCP server for the Safaricom M-Pesa Daraja 3.0 API.
Covers all 26 Daraja products, M-Pesa Ratiba included, checks where inbound callbacks come from, and ships a simulator so you can run every tool without a Safaricom account.
npx daraja-mcpThat 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 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.
Related MCP server: mpesa-mcp
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 |
| Send a payment prompt. Returns an acknowledgement only. |
| Send a prompt and wait for the customer. Returns the receipt. |
| Check the status of a previous prompt. |
| Create a standing order for recurring collection. |
| Create one and wait for the customer to approve. |
| Generate a dynamic QR code. |
Disbursement
Tool | What it does |
| Pay a customer: refunds, withdrawals, salaries. |
| Same, but returns the settled result. |
| Pay a PayBill, a till, or top up a B2C working account. |
| Remit tax to KRA against a PRN. |
| Pay a Pochi la Biashara number. |
Treasury
Tool | What it does |
| Query your business account balance. |
| Look up any past transaction. |
| Reverse a transaction paid into your shortcode. |
Customer to business
Tool | What it does |
| Register validation and confirmation URLs. |
| Simulate a customer payment. Sandbox only. |
| Register for the Pull Transactions API. |
| Fetch C2B transactions for a window. |
Identity and fraud (new in Daraja 3.0)
Tool | What it does |
| When was this number last SIM-swapped? |
| When was this number first registered? |
| Is this number registered to this national ID? |
| 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 |
| Recent callbacks, newest first. |
| Full payload for a correlation id. |
| 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 |
| Insufficient funds |
| Cancelled by user |
| Timeout, customer unreachable |
| Wrong PIN |
| 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:
Set
DARAJA_MODE=productionand real credentials.Set
DARAJA_CALLBACK_PUBLIC_URLto a public HTTPS endpoint.Leave source verification on. It is on by default and the server refuses to let you disable it in production.
Set
DARAJA_CALLBACK_PATH_SECRETto a random string.
Ratiba additionally requires a signed commercial agreement with Safaricom before it works outside the sandbox.
Configuration
Variable | Purpose |
|
|
| From your Daraja app |
| From your Daraja app |
| PayBill or till number |
| Lipa na M-Pesa passkey, for STK push |
| For B2C, B2B, reversals, balance |
| Encrypted initiator password |
| Public URL Safaricom can reach |
| Local listener port, default |
| Unguessable path segment |
| Override allowed source ranges |
| 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 sendInitiator.RecieverIdentifierTypeis misspelled in the specification.B2C expects
Occassion; transaction status expectsOccasion.Ratiba's published sample says
StandingOrderNameNamewhile its parameter table saysStandingOrderName. Both are sent.Ratiba's synchronous response uses
ResponseHeaderand code200; its callback usesresponseHeaderand code0. Different casing, different code space, same product.STK
ResultCodeis 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 checknpm 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
Available Tools
25 toolsaccount_balanceB
Query the balance of your M-Pesa business account. Asynchronous; the balance arrives on a callback as a pipe-delimited string per account type.
Inputs: remarks, resultUrl, shortCode.
b2b_paymentB
Pay another business: a PayBill, a Buy Goods till, or a B2C working account top-up.
Inputs: amount (required), target (required), receiverShortCode (required), remarks, +4 more.
b2c_paymentA
Pay money out to a customer: refunds, withdrawals, salaries, promotional winnings. Asynchronous; the result arrives on a callback.
Inputs: amount (required), phoneNumber (required), remarks, occasion, +3 more.
b2c_payment_and_waitB
Pay money out to a customer and wait for the result callback, returning the receipt number on success.
Inputs: amount (required), phoneNumber (required), remarks, occasion, +4 more.
business_to_pochiC
Pay a Pochi la Biashara number.
Inputs: amount (required), phoneNumber (required), remarks, resultUrl, +1 more.
c2b_register_urlsA
Register the validation and confirmation URLs that Daraja calls when a customer pays your PayBill or till directly. Required once per shortcode before C2B notifications work.
Inputs: shortCode, responseType, validationUrl, confirmationUrl.
c2b_simulateA
Simulate a customer paying your shortcode. Sandbox and simulator only.
Inputs: amount (required), phoneNumber (required), commandId, shortCode, +1 more.
check_age_on_networkA
Return the date a number was first registered on the Safaricom network. Very new lines carry elevated fraud risk.
Inputs: phoneNumber (required).
check_sim_swapA
Return the date a number was last SIM-swapped. A recent swap is a strong fraud signal; check this before disbursing to an unfamiliar number.
Inputs: phoneNumber (required).
generate_qrB
Generate a dynamic M-Pesa QR code for a specific amount and till or paybill.
Inputs: cpi (required), refNo (required), amount (required), trxCode (required), +2 more.
get_callbackA
Fetch the full callback payload for a correlation id.
Inputs: correlationId (required).
list_callbacksA
List callbacks this server has received, newest first.
Inputs: kind, limit.
pull_registerA
Register a shortcode for the Pull Transactions API, which lets you fetch missed C2B transactions after an outage.
Inputs: nominatedNumber (required), shortCode, callbackUrl.
pull_transactionsA
Fetch C2B transactions for a time window. Useful for reconciliation when callbacks were missed.
Inputs: endDate (required), startDate (required), shortCode, offsetValue.
query_org_infoA
Look up the registered name and tariff of a PayBill or till. Use this to confirm you are paying the business you intend to before sending money.
Inputs: shortCode (required), identifierType.
ratiba_createA
Create an M-Pesa Ratiba standing order for recurring collection: subscriptions, loan repayments, insurance premiums, SACCO contributions. The customer approves via an M-Pesa prompt. The standing order name must be unique per customer.
Inputs: amount (required), endDate (required), frequency (required), startDate (required), +7 more.
ratiba_create_and_waitA
Create an M-Pesa Ratiba standing order and wait for the customer to approve it. Returns the settled outcome including the reminder schedule id.
Inputs: amount (required), endDate (required), frequency (required), startDate (required), +8 more.
reversalB
Reverse a transaction that was paid into your shortcode.
Inputs: amount (required), transactionId (required), remarks, resultUrl, +1 more.
server_healthA
Report the current mode, which credentials are configured, and callback receiver status. Start here when something is not working.
Inputs: no named parameters.
stk_pushA
Send an M-Pesa payment prompt (STK push) to a customer. Returns immediately with an acknowledgement; it does NOT confirm payment. Use stk_push_and_wait if you need the outcome.
Inputs: amount (required), phoneNumber (required), shortCode, callbackUrl, +3 more.
stk_push_and_waitA
Send an M-Pesa payment prompt and wait for the customer to accept or decline. Returns the settled outcome including the receipt number on success. Use this when you need to know whether the payment actually completed.
Inputs: amount (required), phoneNumber (required), shortCode, callbackUrl, +4 more.
stk_queryB
Query the status of a previous STK push using its CheckoutRequestID.
Inputs: checkoutRequestId (required), shortCode.
tax_remittanceB
Remit tax to the Kenya Revenue Authority using a Payment Registration Number.
Inputs: amount (required), paymentRegistrationNumber (required), remarks, resultUrl, +1 more.
transaction_statusA
Check the status of any past transaction by receipt number, or by conversation id when the original request timed out. Use this before retrying a payment you are unsure about.
Inputs: remarks, resultUrl, shortCode, transactionId, +1 more.
validate_identityB
Check whether a phone number is registered against a given national ID number.
Inputs: idNumber (required), phoneNumber (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Every tool has a clearly distinct purpose and target. The paired 'and_wait' variants are explicitly distinguished by their descriptions as synchronous vs asynchronous, and other tools like pull_register vs pull_transactions or check_sim_swap vs check_age_on_network are clearly delineated.
All names use snake_case, but the word order is inconsistent: some are verb_noun (check_sim_swap, generate_qr), some noun_verb (stk_push, ratiba_create), and several are pure nouns (b2c_payment, transaction_status). This mixing makes the pattern less predictable, though still readable.
With 25 tools, the server is on the heavy side of typical MCP scopes. While the number is justified by the wide range of M-Pesa APIs covered, it approaches the upper limit of what is manageable without additional organization.
The tool set covers the full M-Pesa transaction lifecycle: collection (C2B, STK, Ratiba), disbursement (B2C, B2B), reconciliation (pull, callbacks, transaction_status), fraud prevention (sim swap, age check, identity validation), and operational needs (health, account_balance, reversal). No major Daraja API operations are missing.
Maintenance
Related MCP Connectors
Kenya payments for AI agents — M-Pesa via Flutterwave. Never holds funds.
Read Africa's Talking balance, incoming SMS, transactions; send SMS, airtime, data and voice calls.
Tanzania payments for AI agents — M-Pesa / Tigo Pesa via Flutterwave. Never holds funds.
Kenyan phone numbers, calls, recordings, AI voice agents and broadcasts, billed in KES.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that integrates AI applications with Safaricom's Daraja API, enabling AI-driven financial transactions and automation through M-Pesa services.14-
- AlicenseAqualityBmaintenanceMCP server for East African fintech APIs — trigger M-Pesa STK Push payments, check transaction status, send SMS to 20+ African networks, and top up airtime via Africa's Talking.5213 PyPI6MIT

PayLink MCP Serverofficial
FlicenseNot gradedqualityDmaintenanceOpen-source MCP server that streamlines payment integration for AI agents and financial apps in Africa, providing unified tools for providers like M-Pesa.1-- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that integrates Safaricom's M-PESA Daraja API with Claude, enabling natural language payment processing and real-time transaction notifications.3-