Daraja Agent KitAgent setup
Add the skills and the MCP server to Claude Code, Codex, Cursor, Copilot, Gemini CLI and other agents.
There are two pieces, installed separately:
- Skills: instructions and scripts the agent reads. They work with any agent that supports the open Agent Skills format.
- MCP server (
mpesa-daraja): tools that call Daraja. It works with any MCP client.
Both start in the sandbox. Production money movement stays off unless you set DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=true.
Skills
You need Node.js 22.20 or later. The skills CLI copies the skills into each agent's folder.
npx skills add Mr-Macharia/mpesa-daraja-skills-and-mcp # choose agents interactively
npx skills add Mr-Macharia/mpesa-daraja-skills-and-mcp -a codex -a cursor # specific agents, this project
npx skills add Mr-Macharia/mpesa-daraja-skills-and-mcp -g # global, all your projects
npx skills add Mr-Macharia/mpesa-daraja-skills-and-mcp --skill daraja-stk-push --skill mpesa-daraja # only some skillsWhere they land:
| Agent | -a id | Project | Global |
|---|---|---|---|
| Claude Code | claude-code | .claude/skills/ | ~/.claude/skills/ |
| Codex | codex | .agents/skills/ | ~/.agents/skills/ |
| Cursor | cursor | .agents/skills/ | ~/.cursor/skills/ |
| GitHub Copilot | github-copilot | .agents/skills/ | ~/.copilot/skills/ |
| Gemini CLI | gemini-cli | .agents/skills/ | ~/.gemini/skills/ |
| Windsurf | windsurf | .windsurf/skills/ | ~/.codeium/windsurf/skills/ |
| Cline | cline | .agents/skills/ | ~/.agents/skills/ |
Each skill is self-contained, so you can install just the ones you need.
Claude Code plugin
The plugin bundles all the skills and the MCP server. The server runs through uvx, so install uv first.
/plugin install mpesa-daraja-skills --marketplace Mr-Macharia/mpesa-daraja-skills-and-mcpOn older Claude Code versions, use two steps: /plugin marketplace add Mr-Macharia/mpesa-daraja-skills-and-mcp, then /plugin install mpesa-daraja-skills@mpesa-daraja. Either way, run uvx mpesa-daraja-mcp init once to save your keys, and answer n when it offers to add the server to Claude Code, so you don't end up with two copies.
MCP server
You need uv. It runs the server straight from PyPI.
curl -LsSf https://astral.sh/uv/install.sh | shEasiest: the setup wizard
uvx mpesa-daraja-mcp initIt asks for your Daraja keys (secrets are typed hidden), checks them live with Safaricom, then saves them to a private config file. It then offers to add the server to every agent it finds: Claude Code, Codex, Gemini CLI and Cursor. Restart your agent and you're done.
- Re-run it any time to change a value. Pressing Enter keeps the current one.
uvx mpesa-daraja-mcp statusshows what's configured, with values masked, and re-tests the keys.
Or add the server by hand
The add command needs no keys:
claude mcp add --scope user mpesa -- uvx mpesa-daraja-mcpThen put your keys in one of these files. The server reads them on start, so restart it after editing.
| File | Use it for |
|---|---|
~/.config/mpesa-daraja-mcp/config.env (Windows: %APPDATA%\mpesa-daraja-mcp\config.env) | Your keys for every project. This is the file the wizard writes |
.env in the project folder | Keys for one project. Only DARAJA_* lines are read |
DARAJA_CONSUMER_KEY=...
DARAJA_CONSUMER_SECRET=...
DARAJA_SHORTCODE=174379
DARAJA_PASSKEY=...If something is missing, the agent can call mpesa_setup_status. It reports what's missing for each feature without ever showing values.
Never commit a file that contains your keys.
Keep context small
Every tool the server offers takes up space in your agent's context. Load only the groups you use, for example DARAJA_TOOLSETS=stk for checkout alone. That cuts the schema the agent reads from about 6,300 tokens to about 2,100.
Groups: stk, c2b, payouts, ops, qr, ratiba, billmanager. The basic tools are always on.
Check it works
Ask your agent:
Check my M-Pesa credentials, then send a KES 1 STK push to 07XXXXXXXX and tell me the result.It should call mpesa_check_credentials, then mpesa_stk_push_and_wait.