The Model Context Protocol is becoming the standard wiring layer between AI agents and external services. Stripe has an MCP server. Twilio has one. GitHub, Notion, Linear — the list is long and growing.
M-Pesa did not have one. Until last week.
mpesa-mcp is a five-tool MCP server that gives any AI agent — Claude, GPT-4o, Gemini, any agent using the protocol — direct access to M-Pesa payments and Africa's Talking SMS. Install it in sixty seconds:
pip install mpesa-mcp
# or, no install needed:
uvx mpesa-mcpPoint your agent config at it and your agent can now:
- Trigger an STK Push — the customer payment prompt that appears directly on a Kenyan phone
- Query the status of any STK Push in real time
- Check any M-Pesa transaction by receipt number
- Send SMS to 1 to 1,000 recipients across 20+ African telecom networks
- Top up airtime programmatically
Why this matters
The gap is not technical. The M-Pesa Daraja API is well-documented and developer-friendly. Africa's Talking is one of the more thoughtfully designed telecom SDKs I've worked with. The gap is presence.
The AI tooling layer — the infrastructure that AI agents use to act in the world — is being built primarily for markets with Stripe accounts and Twilio numbers. An agent that can process a payment in London cannot process a payment in Nairobi. An agent that can send an SMS alert in Chicago cannot send one in Kampala. Not because the underlying infrastructure doesn't exist, but because nobody put in the work to bridge it.
That's a fixable problem. mpesa-mcp is the fix for payments and messaging.
The architecture
The server uses FastMCP — the lightweight Python framework for building MCP servers. Each tool is a decorated function with typed parameters and a clean docstring that serves as the tool description the agent sees:
@mcp.tool()
async def mpesa_stk_push(
phone_number: str,
amount: int,
account_reference: str,
transaction_desc: str
) -> dict:
"""Initiate an M-Pesa STK Push payment request."""The server handles credential loading from environment variables, phone number normalization (every Kenyan format — 07xx, +2547xx, 2547xx — maps to the E.164 variant Daraja requires), base64 password generation with timestamp (the non-obvious part of STK Push authentication), and error mapping to clean status codes.
Four passing tests. CI on Python 3.10, 3.11, 3.12. CC BY-NC-ND licensed.
What's still missing
This is version one. The obvious next tools are C2B registration (merchant till/paybill webhook setup), B2C disbursement (bulk payouts to phone numbers), and account balance queries. USSD session handling is a longer-term addition that would require a different server architecture — USSD is stateful in a way that doesn't map cleanly to the MCP tool model.
The broader gap — beyond payments — is that almost every African infrastructure API is absent from the AI tooling layer. County government open data APIs. Kenya National Bureau of Statistics feeds. NDMA drought early warning data. Each of these is an MCP server waiting to be built.
Source: github.com/gabrielmahia/mpesa-mcp · Listed on awesome-mcp-servers (PR #3022)
Responses