gabrielmahia/mpesa-mcp

> MCP server for East African fintech APIs — M-Pesa (Safaricom Daraja) and Africa's Talking
Give your AI agent the ability to trigger M-Pesa payments, check transaction status, send SMS, and top up airtime across 20+ African telecom networks.
Models
This server does not recommend, certify or benchmark any model, and get_model_hint() is kept only for compatibility (it returns neutral guidance). Use a model that follows tool schemas reliably, rehearse in the sandbox first, and keep a person approving every money-moving or messaging call: in live mode those tools need confirm_send=true and are capped (MPESA_MAX_AMOUNT_KES, default KES 100,000; MPESA_MAX_SMS_RECIPIENTS, default 50).
Why this exists
M-Pesa processes more transactions per day than PayPal does in Africa. Africa's Talking
reaches users in 20+ countries on basic phones via SMS and USSD. Neither has an MCP server.
This means every AI agent built today — Claude, GPT, Gemini, or any MCP-compatible runtime —
cannot trigger an M-Pesa payment or send a Kiswahili SMS without custom integration work.
mpesa-mcp closes that gap in one pip install.
Tools
| Tool | Description |
|---|---|
| mpesa_stk_push | Trigger STK Push payment prompt on customer's M-Pesa phone |
| mpesa_stk_query | Check status of an STK Push request |
| mpesa_transaction_status | Query any M-Pesa transaction by receipt number |
| sms_send | Send SMS to 1–1,000 recipients across African networks |
| airtime_send | Send airtime top-up to any subscriber (KES, NGN, GHS, UGX, etc.) |
Coverage
- **M-Pesa:** Kenya (Safaricom Daraja v3) — STK Push, C2B, transaction status
- **SMS/Airtime:** Kenya, Nigeria, Ghana, Tanzania, Uganda, Rwanda, South Africa, and 15+ more via Africa's Talking
Glama (hosted MCP)
mpesa-mcp is available as a hosted MCP server on Glama:
Security — NSA MCP Guidance Compliant
mpesa-mcp was updated in response to **NSA CSI U/OO/6030316-26 (May 2026)** — the NSA Artificial Intelligence Security Center's Cybersecurity Information Sheet on Model Context Protocol security.
The implementation below documents compliance against the NSA's MCP security framework, control by control.
| NSA Control | Implementation |
|---|---|
| Parameter validation | KE phone regex ^254[17]\d{8}$ + amount bounds [1–150,000 KES] |
| Audit logging | Structured log per tool call; phone numbers SHA-256 hashed |
| Token lifecycle | OAuth token cached with expiry; auto-refreshed |
| Error containment | Structured error dicts; no raw exception propagation |
| HTTPS enforcement | All Daraja API calls HTTPS-only |
| No hardcoded secrets | All credentials via environment variables |
See SECURITY.md for the full compliance table.
> **Reference:** NSA CSI_MCP_SECURITY.pdf — May 2026, UNCLASSIFIED
Install
Or run directly with uvx:
Configuration
Set these environment variables before starting the server:
Sandbox credentials
New Daraja account, or setting this up on a new machine? Follow the sandbox setup guide: it records the verified procedure (create the app with only **Lipa Na M-Pesa Sandbox** ticked, use the published test shortcode and passkey, point MPESA_CALLBACK_URL at a public HTTPS address you can watch) and what a healthy result looks like. Consumer keys cannot be shared, so each developer creates their own free sandbox app.
**M-Pesa sandbox:** https://developer.safaricom.co.ke — create a free app to get test credentials.
- Test shortcode: 174379
- Test passkey: bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
**Africa's Talking sandbox:** https://account.africastalking.com — use username=sandbox, any API key.
Usage with Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
Usage with Claude Code
Set env vars in your shell before running claude.
Example prompts
Once connected, you can ask your AI agent: