Skip to content
MCP server

M-Pesa Daraja

Safaricom Daraja payments for AI agents: STK Push, B2C, QR codes, sandbox first

Runs locally
Install
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-mcp

Add 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 KeyRequired
  • DARAJA_CONSUMER_SECRETDaraja app Consumer SecretRequired
  • DARAJA_ENVsandbox (default) or production
  • DARAJA_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 password
  • DARAJA_CALLBACK_BASE_URLPublic HTTPS base for callback URLs
  • DARAJA_CALLBACK_LISTENhost:port for the built-in callback receiver
  • DARAJA_CALLBACK_TOKEN16+ random characters; secret path for callbacks
  • DARAJA_TOOLSETSComma list: stk,c2b,payouts,ops,qr,ratiba,billmanager
  • DARAJA_READ_ONLYtrue hides every tool that moves money or writes
  • DARAJA_APPROVAL_THRESHOLDPayouts above this many shillings need approval in the chat
  • DARAJA_ALLOWED_RECIPIENTSComma list of phones/shortcodes that payouts may go to
  • DARAJA_ALLOW_LIVE_MONEY_MOVEMENTtrue to allow production charges and payouts
  • DARAJA_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_PASSWORD
  • DARAJA_STATE_DBPath of the SQLite file that stores request state and callbacks
  • DARAJA_OUTPUT_DIRDirectory where generated QR PNGs are saved
  • DARAJA_CONFIG_DIRDirectory holding the saved config (default: user config dir)
  • DARAJA_DOTENVPath of a .env file to load instead of the project one
  • DARAJA_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-signed
  • DARAJA_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.

How AIPoweredBot checks servers