# M-Pesa Daraja

> M-Pesa Daraja is an MCP server for finance and payments. Safaricom Daraja payments for AI agents: STK Push, B2C, QR codes, sandbox first. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** self-hosted, CLI
- **Repository:** https://github.com/mr-macharia/mpesa-daraja-skills-and-mcp/tree/HEAD/mcp-server
- **MCP Registry name:** io.github.Mr-Macharia/mpesa-daraja-mcp
- **Categories:** [finance and payments](https://ai-powered.com/categories/finance-and-payments), [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-15

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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>"
      }
    }
  }
}
```

## Tools

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

## 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.

## Alternatives

- [payware](https://ai-powered.com/mcp/payware): payware is an open-source MCP server for finance and payments.
- [Pink Agentic AI Payments](https://ai-powered.com/mcp/pink-agentic-ai-payments): Pink Agentic AI Payments is a freemium MCP server for finance and payments.
- [AgentPay — trust routing + spend caps for x402 agents](https://ai-powered.com/mcp/agentpay-trust-routing-spend-caps-for-x402-agents): AgentPay — trust routing + spend caps for x402 agents is a freemium MCP server for finance and payments.
- [Agentpay Sentinel MCP](https://ai-powered.com/mcp/agentpay-sentinel-mcp): Agentpay Sentinel MCP is a freemium MCP server for finance and payments.
- [PayPal, guarded](https://ai-powered.com/mcp/paypal-guarded): PayPal, guarded is an MCP server for finance and payments.
- [Saifuban](https://ai-powered.com/mcp/saifuban): Saifuban is a free MCP server for finance and payments.
- [AgentPay](https://ai-powered.com/mcp/agentpay): AgentPay is a paid MCP server for finance and payments.
- [Dodo Payments Docs](https://ai-powered.com/mcp/dodo-payments-docs): Dodo Payments Docs is a free MCP server for finance and payments.

---
Source: https://ai-powered.com/mcp/m-pesa-daraja
