mpesa-daraja-mcp: M-Pesa Daraja MCP server

An MCP server that exposes Safaricom's Daraja APIs as tools, so an agent (Claude Code, Claude Desktop, any MCP client) can test and operate M-Pesa integrations. It pairs with the skills in ../skills: skills teach how to integrate, this server lets the agent call Daraja.

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 MPESA_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

Install & run

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

Until the first PyPI release, run from GitHub instead: uvx --from "git+https://github.com/Mr-Macharia/mpesa-daraja-skills-and-mcp#subdirectory=mcp-server" mpesa-daraja-mcp.

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 MPESA_DOTENV. Only MPESA_* 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 MPESA_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 MPESA_CALLBACK_LISTEN=127.0.0.1:8787
export MPESA_CALLBACK_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(24))")
ngrok http 8787                        # sandbox; use a reverse proxy with TLS in production
export MPESA_CALLBACK_BASE_URL=https://<tunnel-host>

Callbacks are stored in MPESA_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.

Context cost

Pick the smallest set you need with MPESA_TOOLSETS.

Development

pip install -e ".[dev]"
pytest

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

License

MIT. Not affiliated with or endorsed by Safaricom PLC; M-Pesa and Daraja are trademarks of Safaricom PLC.