SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformsmpesa-mcp

mpesa-mcp

M-PESA via the Safaricom Daraja API: STK push, B2C payments, balance queries, transaction status, SIM swap detection and Bill Manager.

Open website

About this tool

Purpose

mpesa-mcp is an MCP (Model Context Protocol) server for connecting AI agents with East African fintech APIs, primarily M-PESA (Safaricom Daraja) and Africa's Talking. It enables AI agents to trigger M-PESA payments, query transaction status, send SMS, and top up airtime on more than 20 African telecom networks.

The project notes that M-PESA processes more daily transaction volume in Africa than PayPal, and Africa's Talking reaches basic phone users in more than 20 countries via SMS and USSD, but neither previously had an MCP server. mpesa-mcp aims to fill this gap, enabling Claude, GPT, Gemini, or any MCP-compatible runtime to invoke these capabilities without custom integrations.

Key capabilities

  • M-PESA (Kenya Safaricom Daraja v3): STK Push, C2B, transaction status query.
  • SMS and airtime: Coverage of more than 20 countries including Kenya, Nigeria, Ghana, Tanzania, Uganda, Rwanda, and South Africa via Africa's Talking.
  • Number of tools: 7 tools in total, covering STK push, B2C, balance query, transaction status, SIM card swap detection, and Bill Manager, among others.
  • Hosted MCP: A hosted MCP server is available on Glama.
  • Server discovery: Through .well-known/mcp.json publishes capabilities, conforming to the emerging MCP Server Cards standard, allowing registries and browsers to index the server's tools without connecting.

Usage

Installation and running:

pip install mpesa-mcp

Or run directly with uvx. Environment variables must be set before starting the server.

Sandbox credentials:

  • M-PESA sandbox:https://developer.safaricom.co.ke — create a free app to get test credentials.
  • Test short code: 174379
  • Test passkey: bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
  • Africa's Talking sandbox:https://account.africastalking.com — use username=sandbox with any API key.

Claude Desktop usage: Add the configuration to ~/Library/Application Support/Claude/claude_desktop_config.json(macOS).

Claude Code usage: Set the environment variables in the shell before running claude.

Example prompts:

  • “Send KES 500 STK Push to +254712345678 for order #1234”
  • “Check if the payment QKL8ABC123 has been received”
  • “Send an SMS to these 50 farmers with today's maize price: [list]”
  • “Top up KES 50 airtime for our field agents: [list of numbers]”

Use cases

  • Field agent payment distribution: Trigger STK Push for multiple field agents in sequence, track each checkout_request_id, and poll for confirmation.
  • Farmer alerts and airtime: Send SMS and top up airtime for large numbers of farmers, covering Safaricom, Airtel, and Telkom.
  • Payment reconciliation: Verify in real time whether an M-PESA transaction succeeded and the amount.

Security and limitations

  • Security compliance: mpesa-mcp is updated in accordance with NSA CSI U/OO/6030316-26 (May 2026), following the NSA AI Security Center's MCP security framework; the full compliance table is in SECURITY.md.
  • Tool annotations: All tools declare MCP tool annotations, allowing clients to request confirmation before triggering payment, SMS, or airtime operations.
  • Live mode limitations: In live mode (MPESA_SANDBOX=false), eight fund-outflow tools (mpesa_b2c, mpesa_business_paybill, mpesa_business_buygoods, mpesa_business_pochi, mpesa_reversal, mpesa_tax_remittance, mpesa_b2b_express_checkout, airtime_send) are restricted:
    • Confirmation: Unless called with confirm_send=trueOtherwise, execution is refused.
    • Upper limit: amounts exceeding MPESA_MAX_AMOUNT_KES (default 100,000; 0 means no upper limit) will be rejected.
    • Opt-out: MPESA_REQUIRE_CONFIRMATION=false removes the confirmation requirement and should be used sparingly only in fully controlled automation setups.
  • Sandbox is unrestricted: customer-approved flows (STK Push, Ratiba, Bill Manager) are unchanged and approved by the customer on their phone.
  • SMS limit: MPESA_MAX_SMS_RECIPIENTS defaults to 50.
  • Model hints: The server does not recommend, certify, or benchmark any model; get_model_hint() is retained only for compatibility (returning neutral guidance). It is recommended to use a model that reliably follows tool schemas, rehearse in the sandbox first, and keep human approval for every funds transfer or message-sending call.
  • Testing and accuracy: MCP ecosystem benchmarks (CData, 2026) found that most MCP servers achieve 60–75% accuracy on complex queries. mpesa-mcp has been tested against three Kenyan phone number formats, boundary amount values, and missing optional fields, and write operations (STK push, SMS, airtime) have explicit validation before calling the API.
  • Secret security: Do not commit API keys; use environment variables or a secrets manager. Report vulnerabilities to contact@aikungfu.dev.

Ecosystem and Protocol

  • Mojaloop + MCP: Mojaloop (funded by the Gates Foundation) handles payment interoperability, connecting banks, mobile wallets, and merchants; mpesa-mcp handles the AI agent tool layer. The two are complementary.
  • MCP vs A2A: mpesa-mcp implements MCP (communication between AI agents and tools). A2A (Agent-to-Agent) handles communication between agents. Most integrations only need MCP; A2A is relevant only when building multi-agent systems.

Related Infrastructure

  • wapimaji-mcp — Kenya water/drought MCP
  • civic-agent-kit — Kenya civic data MCP
  • swahili-health-mcp — Kenya DHIS2 health data MCP
  • kenya-legal-rag — Kenya legal corpus MCP

License and Collaboration

MIT licensed, © 2026 Gabriel Mahia. Feedback via GitHub Issues only; pull requests are not accepted. Demo data is marked DEMO and is not suitable for operational decisions.

Related tools

Browse category