mpesa-daraja-mcp

The MCP server in the M-Pesa Daraja Agent Kit. It lets an AI agent call Safaricom's Daraja API safely.

An MCP server that exposes Safaricom's Daraja APIs as tools, so an agent (Claude Code, Codex, Cursor, Gemini CLI, any MCP client) can collect payments, check whether they went through, and operate M-Pesa from a chat. It starts in the sandbox, and nothing live happens until you switch it on.

It pairs with the Agent Skills in the same kit: the skills teach an agent how to integrate M-Pesa, and this server lets it call Daraja. You can use either on its own.

Who it's for

• Developers building payment integrations: ask your agent to run a request against the sandbox and read the real response.
• Learners finding out how the Daraja API works: send real requests to a safe test environment and see what comes back.
• Businesses and teams that want an AI agent to handle payments: collecting them, checking whether they went through, and reconciling them.

Install

Let your agent do it. Paste this into Claude Code, Codex, Cursor, Gemini CLI or any coding agent:

Add the M-Pesa Daraja MCP server to yourself, named "mpesa", with the command: uvx mpesa-daraja-mcp
It needs no keys in your config. If uv is missing, tell me how to install it first.
Don't ask me for my Daraja keys. Tell me to run `uvx mpesa-daraja-mcp setup` in my own terminal,
which saves them privately, then to restart you.
After I restart you, call mpesa_check_credentials and tell me if everything works.

Or do it yourself. You need uv. The wizard asks for your Daraja keys (secrets are typed hidden), checks them live with Safaricom, saves them to a file only you can read, and registers the server with Claude Code, Codex, Gemini CLI or Cursor:

uvx mpesa-daraja-mcp setup

Then restart your agent and ask: "Check my M-Pesa credentials, then send a KES 1 STK push to 0712345678 and tell me when it's paid." The full Agent Kit, with the skills and more examples, is in the main README.

Tools

Tool annotations mark money-moving tools as destructiveHint, so MCP clients ask for approval.

Safety

• Defaults to the sandbox.
• In production, money-moving tools refuse to run unless DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=true.
• Callback URLs must be HTTPS; C2B URLs with mpesa/safaricom in them are rejected up front.
• Tokens and secrets are never returned in tool output.
• Responses with ResponseCode "0" are tagged _note: ACCEPTED for processing only, so the agent does not report them as completed payments.
• Idempotent money tools. Each request is stored under an idempotency key. Repeating the key returns the stored request (duplicate: true) instead of paying again.
  • Only a definitively FAILED request is re-sent.
  • ACCEPTED or UNKNOWN requests (queue timeouts, network errors) are never re-sent until their result is known.
  • B2C, B2B and B2B Express require an explicit idempotency_key, e.g. refund-order-1042. Reversal, tax and Ratiba derive one from the transaction ID, the PRN and phone + name respectively. For STK the key is optional.

Configuration

Commands and configuration files

uvx mpesa-daraja-mcp setup     # guided: keys (hidden input), live check, save, register with your agents
uvx mpesa-daraja-mcp status    # what's configured (masked) + a live key check
uvx mpesa-daraja-mcp           # the MCP server itself, on stdio: what your agent runs

The server needs no flags or environment variables in your agent's config. Settings are read in this order, highest first:

1. Environment variables, e.g. from the client's env block.
2. A project .env in the folder the agent starts the server in, or the file named by DARAJA_DOTENV. Only DARAJA_* lines are read.
3. The user config file that setup writes: ~/.config/mpesa-daraja-mcp/config.env (Windows: %APPDATA%\mpesa-daraja-mcp\config.env; override the folder with DARAJA_CONFIG_DIR). It is readable only by you.

The server starts even when unconfigured. Tools then explain what's missing, and mpesa_setup_status lists the gaps for each toolset without revealing any values.

To register by hand: claude mcp add --scope user mpesa -- uvx mpesa-daraja-mcp. Every other agent is covered in docs/clients.md. The older mpesa-mcp command still works.

Results and callbacks

Every money or async tool returns one shape:

{"status": "ACCEPTED | SUCCESS | FAILED | UNKNOWN", "message": "...", "idempotency_key": "...",
 "duplicate": false, "ids": {"checkout_request_id": "..."}, "receipt": "...", "result_code": "...",
 "explanation": "...", "raw": {}}

To let the agent see final results, enable the built-in receiver:

export DARAJA_CALLBACK_LISTEN=127.0.0.1:8787
export DARAJA_CALLBACK_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(24))")
ngrok http 8787                        # sandbox; use a reverse proxy with TLS in production
export DARAJA_CALLBACK_BASE_URL=https://<tunnel-host>

Callbacks are stored in DARAJA_STATE_DB:

• mpesa_get_result(id) reads them.
• mpesa_stk_push_and_wait returns the final outcome in one call.
• Queue-timeout callbacks are recorded as UNKNOWN.
• C2B validation requests are always accepted. Use your own receiver if you need to reject payments.

Without the receiver, mpesa_stk_push_and_wait still works through STK Query. For other APIs, paste a received payload into mpesa_parse_callback.

Load only the tools you need

Every tool the server offers takes up space in your agent's context, even when it's never called. Set DARAJA_TOOLSETS to the groups you use, and the agent sees only those tools. The basic tools (core) are always on; leave the setting unset to load everything.

The groups are stk, c2b, payouts, ops, qr, ratiba and billmanager.

Development

pip install -e ".[dev]"
pytest

Tests use respx to mock Daraja. Nothing hits the network.

License

MIT © 2026 Mr-Macharia. An independent open-source project, not affiliated with or endorsed by Safaricom PLC. M-Pesa and Daraja are trademarks of Safaricom PLC.