M-Pesa Daraja

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

What to ask your agent

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.

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:

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

mpesa_stk_push
mpesa_stk_query | | C2B and Pull Transactions | daraja-c2b | mpesa_c2b_register_urls
mpesa_c2b_simulate
mpesa_pull_transactions | | B2C and Pochi la Biashara | daraja-b2c | mpesa_b2c_payment | | B2B, B2C top-up, B2B Express Checkout | daraja-b2b | mpesa_b2b_payment
mpesa_b2b_express_checkout | | Tax remittance (KRA) | daraja-tax-remittance | mpesa_b2b_payment with PayTaxToKRA | | Transaction Status, Account Balance, Reversal | daraja-account-ops | mpesa_transaction_status
mpesa_account_balance
mpesa_reverse_transaction | | Dynamic QR | daraja-dynamic-qr | mpesa_generate_dynamic_qr | | Ratiba (standing orders) | daraja-ratiba | mpesa_ratiba_create_standing_order | | Bill Manager | daraja-bill-manager | mpesa_bill_manager_optin
mpesa_bill_manager_send_invoice
mpesa_bill_manager_cancel_invoice |

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

Safety

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

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

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. When you go live, you are responsible for complying with Safaricom's terms and payments regulation.