{
  "markdown": "# mpesa-mcp\n\n<!-- mcp-name: io.github.gabrielmahia/mpesa-mcp -->\n\n> MCP server for East African fintech APIs — M-Pesa (Safaricom Daraja) and Africa's Talking\n\nGive your AI agent the ability to trigger M-Pesa payments, check transaction status, send SMS, and top up airtime across 20+ African telecom networks.\n\n[![Tests](https://github.com/gabrielmahia/mpesa-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/gabrielmahia/mpesa-mcp/actions)\n[![PyPI](https://img.shields.io/pypi/v/mpesa-mcp)](https://pypi.org/project/mpesa-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Glama Score](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp/badges/score.svg)](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp)\n[![smithery badge](https://smithery.ai/badge/@gabrielmahia/mpesa-mcp)](https://smithery.ai/server/@gabrielmahia/mpesa-mcp)\n[![Glama](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp/badge)](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp)\n[![NSA MCP Compliant](https://img.shields.io/badge/NSA%20CSI%20U%2FOO%2F6030316--26-MCP%20Security%20Compliant-blue)](https://www.nsa.gov/Portals/75/documents/Cybersecurity/CSI_MCP_SECURITY.pdf)\n\n[![mpesa-mcp MCP server](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp/badges/card.svg)](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp)\n\n\n## Tested With\n\n```\nclaude-sonnet-5  (recommended — call get_model_hint() for guidance)\nclaude-opus-4-8  (for highest-accuracy compliance reasoning)\n```\n\nClaude Sonnet 5 (released June 30, 2026) finishes multi-step M-PESA workflows\nwithout stopping short and self-corrects tool-call errors without prompting.\nTerminal-Bench score 80.4% vs Sonnet 4.6's 67.0% — the benchmark most\nanalogous to payment agent work.\n\n\n## Why this exists\n\nM-Pesa processes more transactions per day than PayPal does in Africa. Africa's Talking\nreaches users in 20+ countries on basic phones via SMS and USSD. Neither has an MCP server.\n\nThis means every AI agent built today — Claude, GPT, Gemini, or any MCP-compatible runtime —\ncannot trigger an M-Pesa payment or send a Kiswahili SMS without custom integration work.\n\n`mpesa-mcp` closes that gap in one `pip install`.\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `mpesa_stk_push` | Trigger STK Push payment prompt on customer's M-Pesa phone |\n| `mpesa_stk_query` | Check status of an STK Push request |\n| `mpesa_transaction_status` | Query any M-Pesa transaction by receipt number |\n| `sms_send` | Send SMS to 1–1,000 recipients across African networks |\n| `airtime_send` | Send airtime top-up to any subscriber (KES, NGN, GHS, UGX, etc.) |\n\n## Coverage\n\n- **M-Pesa:** Kenya (Safaricom Daraja v3) — STK Push, C2B, transaction status\n- **SMS/Airtime:** Kenya, Nigeria, Ghana, Tanzania, Uganda, Rwanda, South Africa, and 15+ more via Africa's Talking\n\n\n## Glama (hosted MCP)\n\nmpesa-mcp is available as a hosted MCP server on [Glama](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp):\n\n[![mpesa-mcp MCP server](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp/badges/card.svg)](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp)\n[![mpesa-mcp score](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp/badges/score.svg)](https://glama.ai/mcp/servers/gabrielmahia/mpesa-mcp)\n\n\n\n## Security — NSA MCP Guidance Compliant\n\n`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.\n\nThe implementation below documents compliance against the NSA's MCP security framework, control by control.\n\n| NSA Control | Implementation |\n|---|---|\n| Parameter validation | KE phone regex `^254[17]\\d{8}$` + amount bounds [1–150,000 KES] |\n| Audit logging | Structured log per tool call; phone numbers SHA-256 hashed |\n| Token lifecycle | OAuth token cached with expiry; auto-refreshed |\n| Error containment | Structured error dicts; no raw exception propagation |\n| HTTPS enforcement | All Daraja API calls HTTPS-only |\n| No hardcoded secrets | All credentials via environment variables |\n\nSee [SECURITY.md](./SECURITY.md) for the full compliance table.\n\n> **Reference:** [NSA CSI_MCP_SECURITY.pdf](https://www.nsa.gov/Portals/75/documents/Cybersecurity/CSI_MCP_SECURITY.pdf) — May 2026, UNCLASSIFIED\n\n## Install\n\n```bash\npip install mpesa-mcp\n```\n\nOr run directly with `uvx`:\n\n```bash\nuvx mpesa-mcp\n```\n\n## Configuration\n\nSet these environment variables before starting the server:\n\n```bash\n# M-Pesa (Safaricom Daraja)\nMPESA_CONSUMER_KEY=your_consumer_key\nMPESA_CONSUMER_SECRET=your_consumer_secret\nMPESA_SHORTCODE=174379               # sandbox test shortcode\nMPESA_PASSKEY=your_passkey\nMPESA_CALLBACK_URL=https://yourdomain.com/mpesa/callback\nMPESA_SANDBOX=true                   # set false for production\n\n# Africa's Talking\nAT_USERNAME=sandbox                  # your AT username (sandbox for testing)\nAT_API_KEY=your_at_api_key\n```\n\n### Sandbox credentials\n\n**M-Pesa sandbox:** https://developer.safaricom.co.ke — create a free app to get test credentials.\n- Test shortcode: `174379`\n- Test passkey: `bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919`\n\n**Africa's Talking sandbox:** https://account.africastalking.com — use `username=sandbox`, any API key.\n\n## Usage with Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"mpesa\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mpesa-mcp\"],\n      \"env\": {\n        \"MPESA_CONSUMER_KEY\": \"your_key\",\n        \"MPESA_CONSUMER_SECRET\": \"your_secret\",\n        \"MPESA_SHORTCODE\": \"174379\",\n        \"MPESA_PASSKEY\": \"your_passkey\",\n        \"MPESA_CALLBACK_URL\": \"https://yourdomain.com/mpesa/callback\",\n        \"MPESA_SANDBOX\": \"true\",\n        \"AT_USERNAME\": \"sandbox\",\n        \"AT_API_KEY\": \"your_at_key\"\n      }\n    }\n  }\n}\n```\n\n## Usage with Claude Code\n\n```bash\nclaude mcp add mpesa -- uvx mpesa-mcp\n```\n\nSet env vars in your shell before running `claude`.\n\n## Example prompts\n\nOnce connected, you can ask your AI agent:\n\n> \"Send KES 500 STK Push to +254712345678 for order #1234\"\n\n> \"Check if the payment QKL8ABC123 has been received\"\n\n> \"Send an SMS to these 50 farmers with today's maize price: [list]\"\n\n> \"Top up KES 50 airtime for our field agents: [list of numbers]\"\n\n## Real-world scenarios\n\n**Field agent payment dispatch**\n> \"Send KES 300 STK Push to each of these 12 field agents for today's data collection: [list]\"\n\nThe agent triggers 12 sequential STK pushes, tracks each `checkout_request_id`, and\npolls for confirmation — without any code from you.\n\n**Farmer alert + airtime**\n> \"SMS these 200 Garissa farmers that the river is rising. Then top up KES 20 airtime each so they can call in reports.\"\n\nOne prompt → 200 SMS messages and 200 airtime top-ups across Safaricom, Airtel, and Telkom.\n\n**Payment reconciliation**\n> \"Check whether receipt OKL8M3B2HF was a successful payment and how much it was for\"\n\nUseful for support agents using Claude to verify M-Pesa transactions in real time.\n\n## Tool annotations\n\nAll tools declare [MCP tool annotations](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#tool-annotations) so clients can gate calls appropriately:\n\n| Tool | readOnly | destructive | idempotent |\n|------|----------|-------------|------------|\n| `mpesa_stk_push` | ❌ | ✅ | ❌ |\n| `mpesa_stk_query` | ✅ | ❌ | ✅ |\n| `mpesa_transaction_status` | ✅ | ❌ | ✅ |\n| `sms_send` | ❌ | ✅ | ❌ |\n| `airtime_send` | ❌ | ✅ | ❌ |\n\nClaude Desktop and other MCP clients will request confirmation before triggering payment, SMS, or airtime operations.\n\n## Server discovery\n\nCapabilities are advertised via [`.well-known/mcp.json`](.well-known/mcp.json) — the emerging MCP Server Cards standard. Registries and browsers can index this server's tools without connecting to it.\n\n```bash\n# Check capabilities\ncurl https://raw.githubusercontent.com/gabrielmahia/mpesa-mcp/main/.well-known/mcp.json\n```\n\n## Testing and accuracy\n\nThe MCP ecosystem benchmark (CData, 2026) found most MCP servers accurate 60–75% of the time on complex queries — particularly silent failures on write operations and partial parameter application.\n\nmpesa-mcp is tested against all three Kenyan phone number formats, boundary amount values, and missing optional fields:\n\n```bash\npytest tests/ -v  # run full suite\npytest tests/test_phone_formats.py  # format normalization\npytest tests/test_boundary_amounts.py  # min/max amount edge cases\n```\n\nWrite operations (STK push, SMS, airtime) have explicit validation before any API call is made.\n\n\n## Ecosystem context — Mojaloop + MCP\n\n**Mojaloop** (funded by the Gates Foundation) handles payment *interoperability* — connecting banks, mobile money wallets, and merchants across DFSPs in East Africa and beyond.\n\n**mpesa-mcp** handles the *AI agent tooling layer* — enabling AI coding assistants to trigger and query M-Pesa payments programmatically.\n\nThese are complementary:\n- Mojaloop: the interoperability rails between financial providers\n- mpesa-mcp: the MCP interface layer that connects AI agents to those rails\n\nSee the [Mojaloop documentation contribution](https://github.com/mojaloop/documentation/issues/553) for more on this pattern.\n\n## MCP vs A2A — two different protocols\n\nmpesa-mcp implements **MCP** (Model Context Protocol) — how an AI agent talks to tools.\n\nThere is a complementary protocol, **A2A** (Agent-to-Agent), which handles how agents\ntalk to *each other*. They solve different problems and work together:\n\n- **MCP**: Your AI agent → mpesa-mcp → Daraja API / Africa's Talking\n- **A2A**: Orchestrator agent ↔ payment sub-agent ↔ notification sub-agent\n\nFor most integrations you only need MCP. A2A becomes relevant when you're building\nmulti-agent systems where a payment workflow coordinates with other specialized agents.\n\n---\n## Development\n\n```bash\ngit clone https://github.com/gabrielmahia/mpesa-mcp\ncd mpesa-mcp\npip install -e \".[dev]\"\npytest tests/ -v\n```\n\n## Security\n\nDo not commit API keys. Use environment variables or a secrets manager.  \nReport vulnerabilities to: contact@aikungfu.dev\n\n\n## Research Context\n\n**MCP ecosystem benchmark** (CData, 2026): Most MCP servers achieve 60-75% accuracy on complex queries. mpesa-mcp includes explicit validation and bounds checking to exceed this baseline.\n\n**Swahili AI accuracy** (arXiv:2509.04516, 2025): AI models produce 4× more errors in Swahili than English. mpesa-mcp's Swahili-native tool descriptions are designed to minimize this gap for Swahili-speaking users by eliminating the translation step in tool selection.\n\n**MCP security research** (arXiv:2603.18063, arXiv:2603.21642, 2026): Prompt injection via tool descriptions is the primary MCP attack vector. mpesa-mcp mitigates this through static, versioned tool descriptions and strict input validation.\n\n**Related infrastructure:**\n- [wapimaji-mcp](https://github.com/gabrielmahia/wapimaji-mcp) — Kenya water/drought MCP\n- [civic-agent-kit](https://github.com/gabrielmahia/civic-agent-kit) — Kenya civic data MCP\n- [swahili-health-mcp](https://github.com/gabrielmahia/swahili-health-mcp) — Kenya DHIS2 health data MCP\n- [kenya-legal-rag](https://github.com/gabrielmahia/kenya-legal-rag) — Kenya legal corpus MCP\n- Full portfolio: [gabrielmahia.github.io](https://gabrielmahia.github.io)\n\n## License\n\n[MIT](https://creativecommons.org/licenses/by-nc-nd/4.0/) — © 2026 Gabriel Mahia\n\n\n## Stay updated\n\nGet notified of new releases and East African API developments:\n**[Subscribe to updates →](https://buttondown.com/gabrielmahia)**\n\nOr watch this repo on GitHub for release notifications.\n## Sibling packages\n\n| Package | Install | Description |\n|---------|---------|-------------|\n| [wapimaji-mcp](https://github.com/gabrielmahia/wapimaji-mcp) | `pip install wapimaji-mcp` | Kenya drought intelligence MCP server |\n| [civic-agent-kit](https://github.com/gabrielmahia/civic-agent-kit) | `pip install civic-agent-kit` | East African civic AI SDK |\n## Related packages\n\nAll MIT · All part of the East African civic AI stack\n\n| Package | Install | Description |\n|---------|---------|-------------|\n| [wapimaji-mcp](https://github.com/gabrielmahia/wapimaji-mcp) | `pip install wapimaji-mcp` | Kenya drought intelligence MCP server |\n| [kenya-health-mcp](https://github.com/gabrielmahia/kenya-health-mcp) | `pip install kenya-health-mcp` | Kenya health data MCP — NHIF, facilities, maternal, rights |\n| [civic-agent-kit](https://github.com/gabrielmahia/civic-agent-kit) | `pip install civic-agent-kit` | East African civic AI SDK |\n\nFull portfolio: [gabrielmahia.github.io](https://gabrielmahia.github.io)\n\n## Part of the East Africa Coordination Stack\n\nThis MCP server is one of 32 tools in the Kenya coordination infrastructure.\nConnect it to [`africa-coord-bus`](https://github.com/gabrielmahia/africa-coord-bus) —\nthe coordination event bus that routes signals between domains automatically.\n\n```bash\npip install africa-coord-bus\n```\n\nAll 32 servers: [pypi.org/user/gmahia](https://pypi.org/user/gmahia/)\nLive demo: [coord-cascade-demo](https://github.com/gabrielmahia/coord-cascade-demo)\n\n## IP & Collaboration\n\nMIT licensed. Feedback via GitHub Issues only — pull requests are not accepted. Demo data is labeled DEMO and is not suitable for operational decisions. Full policy: [docs/architecture/IP_POLICY.md](docs/architecture/IP_POLICY.md). Security reports: see [SECURITY.md](SECURITY.md).\n\n<!-- interconnect:v1 -->\n## Part of the East Africa coordination stack\n\n- **Install & run:** `pip install reli-cli && reli list` — 33 MCP servers on the [official MCP Registry](https://registry.modelcontextprotocol.io) under `io.github.gabrielmahia`\n- **Evaluate any model on Swahili agent tasks:** [kipimo](https://github.com/gabrielmahia/kipimo) · [dataset](https://huggingface.co/datasets/gmahia/kipimo) · [leaderboard](https://huggingface.co/spaces/gmahia/kipimo-leaderboard)\n- **Coordinate across servers:** [africa-coord-bus](https://pypi.org/project/africa-coord-bus/) — offline-first event bus with a built-in Kenya routing table\n- **Datasets:** [huggingface.co/gmahia](https://huggingface.co/gmahia) · **Docs hub:** [nairobi-stack](https://github.com/gabrielmahia/nairobi-stack)\n\nModel-agnostic by design: closed APIs, open-weight models, and small distilled models are all first-class citizens.\n<!-- /interconnect:v1 -->\n",
  "bytes": 14375,
  "sha": "7cb59b655c7f959ddfbb016404c2eac19e7a63fa42af567e5122578a577c5a1a",
  "repo_slug": "gabrielmahia/mpesa-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gabrielmahia_mpesa_mcp_65f78d3e/readme"
}