M-Pesa Daraja

Official registry Other

Safaricom M-Pesa Daraja tools: STK Push, C2B, B2C, B2B, QR, Ratiba. Sandbox-first, idempotent.

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package mpesa-daraja-mcp

Claude Code

claude mcp add m-pesa-daraja -e 'DARAJA_CONSUMER_KEY=<your daraja_consumer_key>' -e 'DARAJA_CONSUMER_SECRET=<your daraja_consumer_secret>' -e 'DARAJA_ENV=<DARAJA_ENV>' -e 'DARAJA_SHORTCODE=<DARAJA_SHORTCODE>' -e 'DARAJA_PASSKEY=<your daraja_passkey>' -e 'DARAJA_INITIATOR_NAME=<DARAJA_INITIATOR_NAME>' -e 'DARAJA_SECURITY_CREDENTIAL=<your daraja_security_credential>' -e 'DARAJA_CALLBACK_BASE_URL=<DARAJA_CALLBACK_BASE_URL>' -e 'DARAJA_CALLBACK_LISTEN=<DARAJA_CALLBACK_LISTEN>' -e 'DARAJA_CALLBACK_TOKEN=<your daraja_callback_token>' -e 'DARAJA_TOOLSETS=<DARAJA_TOOLSETS>' -e 'DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=<DARAJA_ALLOW_LIVE_MONEY_MOVEMENT>' -e 'DARAJA_INITIATOR_PASSWORD=<your daraja_initiator_password>' -e 'DARAJA_CERT_PATH=<DARAJA_CERT_PATH>' -e 'DARAJA_STATE_DB=<DARAJA_STATE_DB>' -e 'DARAJA_OUTPUT_DIR=<DARAJA_OUTPUT_DIR>' -e 'DARAJA_CONFIG_DIR=<DARAJA_CONFIG_DIR>' -e 'DARAJA_DOTENV=<DARAJA_DOTENV>' -- uvx mpesa-daraja-mcp==0.1.4

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "m-pesa-daraja": {
            "command": "uvx",
            "args": [
                "mpesa-daraja-mcp==0.1.4"
            ],
            "env": {
                "DARAJA_CONSUMER_KEY": "<your daraja_consumer_key>",
                "DARAJA_CONSUMER_SECRET": "<your daraja_consumer_secret>",
                "DARAJA_ENV": "<DARAJA_ENV>",
                "DARAJA_SHORTCODE": "<DARAJA_SHORTCODE>",
                "DARAJA_PASSKEY": "<your daraja_passkey>",
                "DARAJA_INITIATOR_NAME": "<DARAJA_INITIATOR_NAME>",
                "DARAJA_SECURITY_CREDENTIAL": "<your daraja_security_credential>",
                "DARAJA_CALLBACK_BASE_URL": "<DARAJA_CALLBACK_BASE_URL>",
                "DARAJA_CALLBACK_LISTEN": "<DARAJA_CALLBACK_LISTEN>",
                "DARAJA_CALLBACK_TOKEN": "<your daraja_callback_token>",
                "DARAJA_TOOLSETS": "<DARAJA_TOOLSETS>",
                "DARAJA_ALLOW_LIVE_MONEY_MOVEMENT": "<DARAJA_ALLOW_LIVE_MONEY_MOVEMENT>",
                "DARAJA_INITIATOR_PASSWORD": "<your daraja_initiator_password>",
                "DARAJA_CERT_PATH": "<DARAJA_CERT_PATH>",
                "DARAJA_STATE_DB": "<DARAJA_STATE_DB>",
                "DARAJA_OUTPUT_DIR": "<DARAJA_OUTPUT_DIR>",
                "DARAJA_CONFIG_DIR": "<DARAJA_CONFIG_DIR>",
                "DARAJA_DOTENV": "<DARAJA_DOTENV>"
            }
        }
    }
}

Environment variables

DARAJA_CONSUMER_KEY required secret Daraja app Consumer Key
DARAJA_CONSUMER_SECRET required secret Daraja app Consumer Secret
DARAJA_ENV sandbox (default) or production
DARAJA_SHORTCODE Paybill / store number (174379 in sandbox)
DARAJA_PASSKEY secret M-Pesa Express passkey (STK Push)
DARAJA_INITIATOR_NAME API operator username (B2C, B2B, status, balance, reversal)
DARAJA_SECURITY_CREDENTIAL secret Encrypted initiator password
DARAJA_CALLBACK_BASE_URL Public HTTPS base for callback URLs
DARAJA_CALLBACK_LISTEN host:port for the built-in callback receiver
DARAJA_CALLBACK_TOKEN secret 16+ random characters; secret path for callbacks
DARAJA_TOOLSETS Comma list: stk,c2b,payouts,ops,qr,ratiba,billmanager
DARAJA_ALLOW_LIVE_MONEY_MOVEMENT true to allow production charges and payouts
DARAJA_INITIATOR_PASSWORD secret Initiator password, encrypted into SecurityCredential at startup (alternative to DARAJA_SECURITY_CREDENTIAL)
DARAJA_CERT_PATH Path to Safaricom's public certificate, used with DARAJA_INITIATOR_PASSWORD
DARAJA_STATE_DB Path of the SQLite file that stores request state and callbacks
DARAJA_OUTPUT_DIR Directory where generated QR PNGs are saved
DARAJA_CONFIG_DIR Directory holding the saved config (default: user config dir)
DARAJA_DOTENV Path of a .env file to load instead of the project one

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents

Use cases
Three ways to use it
Quick start
How it works
Why this exists
What's inside
Safety
FAQ
Documentation
Contributing
License

M-Pesa Daraja Agent Kit: Agent Skills that teach your agent to use Daraja API, and an MCP server that lets it call Daraja safely.

Works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and any agent that supports Agent Skills or MCP.

Use cases | Choose a setup | Quick start | Safety | Docs

Use cases

Who it helps

Team	What the kit does for them
Developers	A coding agent that writes correct Daraja code: STK checkout, B2C payouts, callback handlers, retries that never pay twice. It also reviews and fixes an existing integration
Online shops and SaaS	Checkout at the till or in the app, Dynamic QR at the counter, subscriptions through Ratiba standing orders
Support teams	An agent that answers "did my payment go through?" from the transaction itself, not a guess
Finance and operations	Reconciling C2B payments against invoices, balance checks, reversals and status lookups from chat
Platforms that pay people	Payouts to drivers, riders, agents and suppliers, safe to retry because every request is idempotent
Landlords, schools, chamas and SACCOs	Invoices and reminders through Bill Manager, contributions collected by STK Push
Businesses filing tax	KRA remittance through B2B, with the right command and fields
Anyone learning Daraja	Sandbox experiments with real responses, and docs that explain why each rule exists

What to ask your agent

Ask	Uses
"Add M-Pesa checkout to my Django order flow, with a callback that marks orders paid."	Skills
"Send KES 250 to 0712345678 for order #1042 and wait for the result."	MCP
"Build a B2C payout job for driver earnings that never pays twice."	Skills
"A customer says they paid. Did receipt TJK7Q2X9LM go through?"	MCP
"My STK push returns 400.002.02. What's wrong with this request?"	Skills
"Pull yesterday's C2B transactions and match them against my invoices."	Both
"Set up a monthly KES 500 standing order for this subscriber."	Both
"Opt my paybill into Bill Manager and invoice these 20 tenants."	Both

Three ways to use it

The two halves are independent. Pick the one that fits the job, or use both.

Skills only MCP server only Skills + MCP server recommended

Your agent writes M-Pesa code for your app: STK checkout, B2C payouts, callback handlers. The skills give it Daraja's rules and tested scripts, so the code is right the first time.

Pick this when you're building an integration in your own codebase.

Your agent calls Daraja for you: sends an STK push, checks a balance, looks up a transaction, reverses a payment. Nothing to write; results come back as SUCCESS, FAILED or UNKNOWN.

Pick this when you want to operate M-Pesa from chat, or test against the sandbox.

The skills tell your agent which tool to call and why. The server makes the call safely. Build the integration and try it live in the same conversation.

Pick this when you want the agent to build and verify.

npx skills add \
  Mr-Macharia/mpesa-daraja-skills-and-mcp

uvx mpesa-daraja-mcp setup

Run both commands.

Quick start

Let your agent install it

Paste this into Claude Code, Codex, Cursor, Gemini CLI or any coding agent:

Install the M-Pesa Daraja Agent Kit for me:
1. Install the Agent Skills for yourself: npx skills add Mr-Macharia/mpesa-daraja-skills-and-mcp -a <your agent id>
   (agent ids: claude-code, codex, cursor, github-copilot, gemini-cli). Use -g if I want them in every project.
2. Add the 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.
3. 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.
4. After I restart you, call mpesa_check_credentials and tell me if everything works.

Your agent installs both halves; you only type your Daraja keys into the setup wizard, never into the chat.

Claude Code: one plugin for both

The plugin installs all 15 skills and the MCP server in one step. The server runs through uv, so install that first, and make sure uvx is on the PATH Claude Code sees:

/plugin install mpesa-daraja-skills --marketplace Mr-Macharia/mpesa-daraja-skills-and-mcp

Then run uvx mpesa-daraja-mcp setup once in a terminal to save your Daraja keys. When it offers to add the server to Claude Code, answer n: the plugin already did. Restart Claude Code.

Or install it yourself

1. Install the skills. Needs Node.js 22.20 or later.

npx skills add Mr-Macharia/mpesa-daraja-skills-and-mcp

2. Install the MCP server. Needs uv.

uvx mpesa-daraja-mcp setup

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. Restart your agent when it's done.

Add the server to one agent by hand

No keys go in these commands; the server reads them from its config file.

Agent	Command
Claude Code	`claude mcp add --scope user mpesa -- uvx mpesa-daraja-mcp`
Codex	`codex mcp add mpesa -- uvx mpesa-daraja-mcp`
Gemini CLI	`gemini mcp add --scope user mpesa uvx mpesa-daraja-mcp`
Cursor, VS Code, others	JSON snippets in docs/clients.md

Then run uvx mpesa-daraja-mcp setup to save your keys, or write the config file yourself as described in docs/clients.md.

Try it

Check my M-Pesa credentials, then send a KES 1 STK push to 0712345678 and tell me when it's paid.

The agent calls mpesa_check_credentials, then mpesa_stk_push_and_wait, and answers with one of three results:

Result	Meaning
`SUCCESS`	Paid. Includes the M-Pesa receipt number
`FAILED`	Not paid, with the reason, e.g. `1032`: the customer cancelled
`UNKNOWN`	Not known yet, with what to check next. Never retried blindly

Everything starts in the sandbox. No real money moves until you opt in.

How it works

Why this exists

M-Pesa Daraja Agent Kit makes M-Pesa payment handling and integration easier for:

Developers building payment integration systems. With the kit, your coding agent knows the Daraja API, so you describe the integration and review the code, instead of piecing it together from the portal. Test it all in the sandbox before going live.
Learners finding out how the Daraja API works. Send real requests to the sandbox, a safe test environment, see what comes back, and read docs that explain why each step exists.
Businesses and teams that want an AI agent to handle payments: collecting them, checking whether they went through, and reconciling them through an agent.

What's inside

15 Agent Skills. Every major Daraja API, plus helper skills for callbacks, sandbox setup and go-live, credentials and security, and troubleshooting. Each skill bundles tested scripts that validate requests, build STK passwords, encrypt credentials and parse callbacks, so the agent runs known-good code instead of improvising.

The MCP server, mpesa-daraja-mcp. 24 mpesa_* tools. mpesa_stk_push_and_wait returns a payment's final outcome in one call, and an optional built-in callback receiver records results for mpesa_get_result.

Load only what 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. For example, DARAJA_TOOLSETS=stk for a shop that only takes STK payments, or stk,payouts if it also pays people. The groups are stk, c2b, payouts, ops, qr, ratiba and billmanager; the basic tools (core) are always on. Leave it unset to load everything.

Supported Daraja APIs, skills and tools

Daraja API	Skill	MCP tools
OAuth	daraja-auth	`mpesa_check_credentials`
M-Pesa Express (STK Push)	daraja-stk-push	`mpesa_stk_push_and_wait`

Offline tools also explain result codes, normalise phone numbers, build STK passwords and parse callbacks, with no Daraja call.

Safety

Risk	Safeguard
Moving real money by accident	Sandbox by default. In production, money tools refuse to run until `DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=true`, and they're flagged as destructive so clients ask first
Paying twice on a retry	Each money request is stored under an idempotency key. Repeating the key returns the stored outcome; only a definite failure can be re-sent
Reporting "accepted" as "paid"	Only a callback or a status query can produce `SUCCESS`
Malformed requests	Bodies are checked against Daraja's rules before sending, using the same validator as the skills
Leaked secrets	Tokens and secrets never appear in tool output, keys never go in agent config, and callback URLs carry a secret path token

Found a security problem? Report it privately, as described in SECURITY.md.

FAQ

Do I need a Safaricom account?

A free Daraja developer account and a sandbox app, for its Consumer Key and Secret. Sandbox shortcode 174379 and its passkey work out of the box for STK Push.

Will it charge real money?

Only if you set DARAJA_ENV=production with live keys and DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=true.

Why didn't I get a receipt?

Safaricom sends the receipt to your callback URL. Set DARAJA_CALLBACK_BASE_URL to a public HTTPS address, such as an ngrok tunnel to the built-in receiver. Without one, mpesa_stk_push_and_wait still reports the outcome through STK Query, just without the receipt number. See the callback receiver.

My agent says "Connection closed".

Run uvx mpesa-daraja-mcp status. It lists missing settings and re-tests your keys. Then restart the agent.

Documentation

Read	For
docs/clients.md	Setup for each agent: skills folders, MCP config, config files
mcp-server/README.md	Every tool and setting, the callback receiver, toolsets
skills/README.md	The skill catalogue, and why each skill is built the way it is
docs/	How Daraja works: transaction types, callbacks, OAuth, credentials, sandbox
AGENTS.md	Rules for AI agents working on M-Pesa code or on this repo

Contributing

Bug reports, Daraja corrections and new skills are welcome. Start with CONTRIBUTING.md, which covers the dev setup, tests and release process, and follow the Code of Conduct. Changes are recorded in CHANGELOG.md.

License

An independent open-source project, not affiliated with or endorsed by Safaricom PLC. M-Pesa and Daraja are trademarks of Safaricom PLC. When you go live, you are responsible for complying with Safaricom's terms and payments regulation.

Frequently asked questions

What is M-Pesa Daraja?

Safaricom M-Pesa Daraja tools: STK Push, C2B, B2C, B2B, QR, Ratiba. Sandbox-first, idempotent.

How do I install M-Pesa Daraja?

It runs on your machine. In Claude Code: claude mcp add m-pesa-daraja -e 'DARAJA_CONSUMER_KEY=<your daraja_consumer_key>' -e 'DARAJA_CONSUMER_SECRET=<your daraja_consumer_secret>' -e 'DARAJA_ENV=<DARAJA_ENV>' -e 'DARAJA_SHORTCODE=<DARAJA_SHORTCODE>' -e 'DARAJA_PASSKEY=<your daraja_passkey>' -e 'DARAJA_INITIATOR_NAME=<DARAJA_INITIATOR_NAME>' -e 'DARAJA_SECURITY_CREDENTIAL=<your daraja_security_credential>' -e 'DARAJA_CALLBACK_BASE_URL=<DARAJA_CALLBACK_BASE_URL>' -e 'DARAJA_CALLBACK_LISTEN=<DARAJA_CALLBACK_LISTEN>' -e 'DARAJA_CALLBACK_TOKEN=<your daraja_callback_token>' -e 'DARAJA_TOOLSETS=<DARAJA_TOOLSETS>' -e 'DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=<DARAJA_ALLOW_LIVE_MONEY_MOVEMENT>' -e 'DARAJA_INITIATOR_PASSWORD=<your daraja_initiator_password>' -e 'DARAJA_CERT_PATH=<DARAJA_CERT_PATH>' -e 'DARAJA_STATE_DB=<DARAJA_STATE_DB>' -e 'DARAJA_OUTPUT_DIR=<DARAJA_OUTPUT_DIR>' -e 'DARAJA_CONFIG_DIR=<DARAJA_CONFIG_DIR>' -e 'DARAJA_DOTENV=<DARAJA_DOTENV>' -- uvx mpesa-daraja-mcp==0.1.4. For other clients, paste the JSON configuration from this page into their MCP settings.

Does M-Pesa Daraja need an API key?

Yes. It expects DARAJA_CONSUMER_KEY, DARAJA_CONSUMER_SECRET, DARAJA_PASSKEY, DARAJA_SECURITY_CREDENTIAL, DARAJA_CALLBACK_TOKEN, DARAJA_INITIATOR_PASSWORD, which you set in its configuration.

Is M-Pesa Daraja open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains M-Pesa Daraja?

It is published by Mr-Macharia. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.

Server details

Listed in: Official MCP Registry
Publisher: Mr-Macharia
Category: Other
Runs: Local
GitHub stars: ★ 3
License: MIT
Language: Python
Last commit: Oct 24, 2026
Open issues: 4
Version: 0.1.4
Published: Oct 24, 2026

io.github.Mr-Macharia/mpesa-daraja-mcp

Similar servers

Witcher 3 String Editor MCP server for reading and editing The Witcher 3 .w3strings localization files.
Hetzner Cloud (unofficial) Unofficial MCP server for the Hetzner Cloud API: one typed tool per operation, read and...
CIPP MCP - Microsoft 365, Entra ID, Intune, Exchange, Defender, GDAP MSP MCP for CIPP: Microsoft 365, Entra ID, Intune, Exchange, Defender and GDAP across a...
Snipe-IT (unofficial) Unofficial MCP server for the Snipe-IT REST API: assets, users, licenses, guarded writes.
mcp-hub Many stdio MCP servers from one container, published over HTTPS with OAuth 2.1 for any ...
S1000D BREX (S1000D Stack) Read S1000D BREX business rules and check data modules against them, layer by layer.
Impact Plexus Find Canadian and US funders and funding opportunities from public charity and grant fi...
Wärmepumpen-Vorcheck Heat-pump readiness check for German single-family houses: traffic light, reasons, next...

Other