M-Pesa Daraja
Safaricom Daraja payments for AI agents: STK Push, B2C, QR codes, sandbox first
- Platforms
- self-hosted, CLI
- Runs
- Locally
- Version
- 0.1.6
- Listing updated
- 4 days ago
Similar MCP servers
About M-Pesa Daraja
M-Pesa Daraja is an MCP server for finance and payments. It runs locally on your machine and is started by your AI client.
Money-moving calls are guarded by several layers. The server starts in the Daraja sandbox, and in production the tools that charge or pay out refuse to run until DARAJA_ALLOW_LIVE_MONEY_MOVEMENT is set to true. A read-only switch hides every tool that writes, and payouts above a set shilling amount pause for a yes or no in the chat.
Each money request is stored under an idempotency key in a local SQLite file, so a repeated call returns the saved request instead of paying twice. Requests that are accepted or of unknown outcome are never re-sent until their result is known. Callbacks can be captured by a built-in receiver and forwarded, HMAC-signed, to your own app.
It comes from the M-Pesa Daraja Agent Kit and pairs with a set of Agent Skills that teach an agent how to integrate M-Pesa. The README names developers, learners and businesses as its audience, and says the server runs over stdio or an optional bearer-token HTTP mode.
Install
Run in a terminal
claude mcp add mpesa-daraja-mcp --env DARAJA_CONSUMER_KEY='<DARAJA_CONSUMER_KEY>' --env DARAJA_CONSUMER_SECRET='<DARAJA_CONSUMER_SECRET>' --env DARAJA_PASSKEY='<DARAJA_PASSKEY>' --env DARAJA_SECURITY_CREDENTIAL='<DARAJA_SECURITY_CREDENTIAL>' --env DARAJA_CALLBACK_TOKEN='<DARAJA_CALLBACK_TOKEN>' --env DARAJA_INITIATOR_PASSWORD='<DARAJA_INITIATOR_PASSWORD>' --env DARAJA_MCP_TOKEN='<DARAJA_MCP_TOKEN>' --env DARAJA_FORWARD_SECRET='<DARAJA_FORWARD_SECRET>' -- uvx mpesa-daraja-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"mpesa-daraja-mcp": {
"command": "uvx",
"args": [
"mpesa-daraja-mcp"
],
"env": {
"DARAJA_CONSUMER_KEY": "<DARAJA_CONSUMER_KEY>",
"DARAJA_CONSUMER_SECRET": "<DARAJA_CONSUMER_SECRET>",
"DARAJA_PASSKEY": "<DARAJA_PASSKEY>",
"DARAJA_SECURITY_CREDENTIAL": "<DARAJA_SECURITY_CREDENTIAL>",
"DARAJA_CALLBACK_TOKEN": "<DARAJA_CALLBACK_TOKEN>",
"DARAJA_INITIATOR_PASSWORD": "<DARAJA_INITIATOR_PASSWORD>",
"DARAJA_MCP_TOKEN": "<DARAJA_MCP_TOKEN>",
"DARAJA_FORWARD_SECRET": "<DARAJA_FORWARD_SECRET>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"mpesa-daraja-mcp": {
"command": "uvx",
"args": [
"mpesa-daraja-mcp"
],
"env": {
"DARAJA_CONSUMER_KEY": "<DARAJA_CONSUMER_KEY>",
"DARAJA_CONSUMER_SECRET": "<DARAJA_CONSUMER_SECRET>",
"DARAJA_PASSKEY": "<DARAJA_PASSKEY>",
"DARAJA_SECURITY_CREDENTIAL": "<DARAJA_SECURITY_CREDENTIAL>",
"DARAJA_CALLBACK_TOKEN": "<DARAJA_CALLBACK_TOKEN>",
"DARAJA_INITIATOR_PASSWORD": "<DARAJA_INITIATOR_PASSWORD>",
"DARAJA_MCP_TOKEN": "<DARAJA_MCP_TOKEN>",
"DARAJA_FORWARD_SECRET": "<DARAJA_FORWARD_SECRET>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"mpesa-daraja-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"mpesa-daraja-mcp"
],
"env": {
"DARAJA_CONSUMER_KEY": "<DARAJA_CONSUMER_KEY>",
"DARAJA_CONSUMER_SECRET": "<DARAJA_CONSUMER_SECRET>",
"DARAJA_PASSKEY": "<DARAJA_PASSKEY>",
"DARAJA_SECURITY_CREDENTIAL": "<DARAJA_SECURITY_CREDENTIAL>",
"DARAJA_CALLBACK_TOKEN": "<DARAJA_CALLBACK_TOKEN>",
"DARAJA_INITIATOR_PASSWORD": "<DARAJA_INITIATOR_PASSWORD>",
"DARAJA_MCP_TOKEN": "<DARAJA_MCP_TOKEN>",
"DARAJA_FORWARD_SECRET": "<DARAJA_FORWARD_SECRET>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"mpesa-daraja-mcp": {
"command": "uvx",
"args": [
"mpesa-daraja-mcp"
],
"env": {
"DARAJA_CONSUMER_KEY": "<DARAJA_CONSUMER_KEY>",
"DARAJA_CONSUMER_SECRET": "<DARAJA_CONSUMER_SECRET>",
"DARAJA_PASSKEY": "<DARAJA_PASSKEY>",
"DARAJA_SECURITY_CREDENTIAL": "<DARAJA_SECURITY_CREDENTIAL>",
"DARAJA_CALLBACK_TOKEN": "<DARAJA_CALLBACK_TOKEN>",
"DARAJA_INITIATOR_PASSWORD": "<DARAJA_INITIATOR_PASSWORD>",
"DARAJA_MCP_TOKEN": "<DARAJA_MCP_TOKEN>",
"DARAJA_FORWARD_SECRET": "<DARAJA_FORWARD_SECRET>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"mpesa-daraja-mcp": {
"command": "uvx",
"args": [
"mpesa-daraja-mcp"
],
"env": {
"DARAJA_CONSUMER_KEY": "<DARAJA_CONSUMER_KEY>",
"DARAJA_CONSUMER_SECRET": "<DARAJA_CONSUMER_SECRET>",
"DARAJA_PASSKEY": "<DARAJA_PASSKEY>",
"DARAJA_SECURITY_CREDENTIAL": "<DARAJA_SECURITY_CREDENTIAL>",
"DARAJA_CALLBACK_TOKEN": "<DARAJA_CALLBACK_TOKEN>",
"DARAJA_INITIATOR_PASSWORD": "<DARAJA_INITIATOR_PASSWORD>",
"DARAJA_MCP_TOKEN": "<DARAJA_MCP_TOKEN>",
"DARAJA_FORWARD_SECRET": "<DARAJA_FORWARD_SECRET>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
DARAJA_CONSUMER_KEYDaraja app Consumer KeyRequiredDARAJA_CONSUMER_SECRETDaraja app Consumer SecretRequiredDARAJA_ENVsandbox (default) or productionDARAJA_SHORTCODEPaybill / store number (174379 in sandbox)DARAJA_PASSKEYM-Pesa Express passkey (STK Push)DARAJA_INITIATOR_NAMEAPI operator username (B2C, B2B, status, balance, reversal)DARAJA_SECURITY_CREDENTIALEncrypted initiator passwordDARAJA_CALLBACK_BASE_URLPublic HTTPS base for callback URLsDARAJA_CALLBACK_LISTENhost:port for the built-in callback receiverDARAJA_CALLBACK_TOKEN16+ random characters; secret path for callbacksDARAJA_TOOLSETSComma list: stk,c2b,payouts,ops,qr,ratiba,billmanagerDARAJA_READ_ONLYtrue hides every tool that moves money or writesDARAJA_APPROVAL_THRESHOLDPayouts above this many shillings need approval in the chatDARAJA_ALLOWED_RECIPIENTSComma list of phones/shortcodes that payouts may go toDARAJA_ALLOW_LIVE_MONEY_MOVEMENTtrue to allow production charges and payoutsDARAJA_INITIATOR_PASSWORDInitiator password, encrypted into SecurityCredential at startup (alternative to DARAJA_SECURITY_CREDENTIAL)DARAJA_CERT_PATHPath to Safaricom's public certificate, used with DARAJA_INITIATOR_PASSWORDDARAJA_STATE_DBPath of the SQLite file that stores request state and callbacksDARAJA_OUTPUT_DIRDirectory where generated QR PNGs are savedDARAJA_CONFIG_DIRDirectory holding the saved config (default: user config dir)DARAJA_DOTENVPath of a .env file to load instead of the project oneDARAJA_MCP_TOKENBearer token for HTTP mode (32+ random characters)DARAJA_MCP_HOSTHTTP mode bind address (default 127.0.0.1)DARAJA_MCP_PORTHTTP mode port (default 8000)DARAJA_FORWARD_URLYour app's URL: every callback is POSTed on to it, HMAC-signedDARAJA_FORWARD_SECRETHMAC secret for forwarded callbacks (16+ characters)
Tools this server provides (24)
Taken from the project documentation; the running server may differ.
- mpesa_explain_code
- Offline error and result code lookup
- mpesa_normalize_phone
- Converts 07… numbers to 2547… format
- mpesa_generate_stk_password
- Offline password and EAT timestamp for STK Push
- mpesa_parse_callback
- Parses any callback payload
- mpesa_setup_status
- Shows what is configured and missing per toolset
- mpesa_check_credentials
- Checks the OAuth token without returning it
- mpesa_get_result
- Final status by idempotency key or Daraja ID
- mpesa_stk_push_and_wait
- Sends an M-Pesa Express push and waits for the outcome
- mpesa_stk_push
- M-Pesa Express push, fire-and-forget
- mpesa_stk_query
- M-Pesa Express status query
- mpesa_c2b_register_urls
- Registers C2B v2 URLs
- mpesa_c2b_simulate
- Simulates C2B payments in the sandbox only
- mpesa_pull_transactions
- Pull Transactions query
- mpesa_b2c_payment
- B2C v3 and B2Pochi payments
- mpesa_b2b_payment
- BusinessPayBill, BuyGoods, PayToBulk and KRA tax payments
- mpesa_b2b_express_checkout
- B2B USSD push
- mpesa_transaction_status
- Transaction status (async result)
- mpesa_account_balance
- Account balance (async result)
- mpesa_reverse_transaction
- Reverses a transaction
- mpesa_generate_dynamic_qr
- Generates a dynamic QR saved as a PNG file
- mpesa_ratiba_create_standing_order
- Creates an M-Pesa Ratiba standing order
- mpesa_bill_manager_optin
- Bill Manager opt-in
- mpesa_bill_manager_send_invoice
- Sends a Bill Manager invoice
- mpesa_bill_manager_cancel_invoice
- Cancels a Bill Manager invoice
What it does
- STK Push and wait
- Sends an M-Pesa Express push and waits for the callback or polls the query, returning success, failed or unknown.
- Payouts and transfers
- Covers B2C, B2B, bill-pay, buy-goods and tax payments to KRA through separate tools.
- Approval threshold
- Payouts above a configured amount ask for confirmation in the chat before anything is sent.
- Idempotent requests
- Every money request is stored under a key, so retries do not pay twice.
- Toolset selection
- A comma list lets you enable only the groups you need, such as stk, c2b, payouts, qr or ratiba.
- Offline helpers
- Look up result codes, normalise phone numbers and parse callback payloads without calling Safaricom.
Good for
- Collect a customer payment by STK push and report when it is paid
- Test Daraja requests against the sandbox while building an integration
- Reconcile payments from a read-only support or finance bot
- Generate a dynamic QR code for a till or paybill
- Refund a customer with B2C and the original receipt attached
Pricing
Pricing unknown
Distributed as a PyPI package; licence and pricing are not published
M-Pesa Daraja FAQ
How do I install it?
Run `uvx mpesa-daraja-mcp init` to enter your Daraja keys and register the server with Claude Code, Codex, Gemini CLI or Cursor. The package needs uv.
Does it use real money by default?
No. It defaults to the sandbox, and production charges and payouts need DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=true.
Can I stop it moving money at all?
Yes. Setting DARAJA_READ_ONLY=true hides every tool that moves money or writes.
What credentials does it need?
A Daraja consumer key and secret are required. Tools such as STK Push or payouts also need a shortcode, passkey or initiator credentials.
How do I add M-Pesa Daraja to Claude Code?
Run this command in your terminal: claude mcp add mpesa-daraja-mcp --env DARAJA_CONSUMER_KEY='<DARAJA_CONSUMER_KEY>' --env DARAJA_CONSUMER_SECRET='<DARAJA_CONSUMER_SECRET>' --env DARAJA_PASSKEY='<DARAJA_PASSKEY>' --env DARAJA_SECURITY_CREDENTIAL='<DARAJA_SECURITY_CREDENTIAL>' --env DARAJA_CALLBACK_TOKEN='<DARAJA_CALLBACK_TOKEN>' --env DARAJA_INITIATOR_PASSWORD='<DARAJA_INITIATOR_PASSWORD>' --env DARAJA_MCP_TOKEN='<DARAJA_MCP_TOKEN>' --env DARAJA_FORWARD_SECRET='<DARAJA_FORWARD_SECRET>' -- uvx mpesa-daraja-mcp
What are the best alternatives to M-Pesa Daraja?
The closest alternatives to M-Pesa Daraja are payware, Pink Agentic AI Payments, AgentPay — trust routing + spend caps for x402 agents, Agentpay Sentinel MCP and PayPal, guarded.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.