mpesa-mcp
mpesa-mcp
MCP-Server für ostafrikanische Fintech-APIs – M-Pesa (Safaricom Daraja) und Africa's Talking
Geben Sie Ihrem KI-Agenten die Fähigkeit, M-Pesa-Zahlungen auszulösen, den Transaktionsstatus zu prüfen, SMS zu versenden und Guthaben in über 20 afrikanischen Telekommunikationsnetzen aufzuladen.
Warum existiert dieses Projekt?
M-Pesa verarbeitet in Afrika täglich mehr Transaktionen als PayPal. Africa's Talking erreicht Nutzer in über 20 Ländern auf einfachen Mobiltelefonen per SMS und USSD. Keiner von beiden verfügt über einen MCP-Server.
Das bedeutet, dass jeder heute entwickelte KI-Agent – Claude, GPT, Gemini oder eine andere MCP-kompatible Laufzeitumgebung – keine M-Pesa-Zahlung auslösen oder eine SMS auf Kiswahili senden kann, ohne dass benutzerdefinierte Integrationsarbeit geleistet wird.
mpesa-mcp schließt diese Lücke mit einem einzigen pip install.
Related MCP server: M-Pesa MCP Server
Tools
Tool | Beschreibung |
| Löst eine STK-Push-Zahlungsaufforderung auf dem M-Pesa-Telefon des Kunden aus |
| Prüft den Status einer STK-Push-Anfrage |
| Fragt jede M-Pesa-Transaktion anhand der Quittungsnummer ab |
| Sendet SMS an 1–1.000 Empfänger in afrikanischen Netzwerken |
| Sendet Guthabenaufladungen an jeden Teilnehmer (KES, NGN, GHS, UGX usw.) |
Abdeckung
M-Pesa: Kenia (Safaricom Daraja v3) – STK Push, C2B, Transaktionsstatus
SMS/Guthaben: Kenia, Nigeria, Ghana, Tansania, Uganda, Ruanda, Südafrika und über 15 weitere über Africa's Talking
Glama (gehostetes MCP)
mpesa-mcp ist als gehosteter MCP-Server auf Glama verfügbar:
Installation
pip install mpesa-mcpOder führen Sie es direkt mit uvx aus:
uvx mpesa-mcpKonfiguration
Setzen Sie diese Umgebungsvariablen, bevor Sie den Server starten:
# M-Pesa (Safaricom Daraja)
MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_SHORTCODE=174379 # sandbox test shortcode
MPESA_PASSKEY=your_passkey
MPESA_CALLBACK_URL=https://yourdomain.com/mpesa/callback
MPESA_SANDBOX=true # set false for production
# Africa's Talking
AT_USERNAME=sandbox # your AT username (sandbox for testing)
AT_API_KEY=your_at_api_keySandbox-Anmeldedaten
M-Pesa Sandbox: https://developer.safaricom.co.ke – erstellen Sie eine kostenlose App, um Test-Anmeldedaten zu erhalten.
Test-Kurzwahlnummer:
174379Test-Passkey:
bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
Africa's Talking Sandbox: https://account.africastalking.com – verwenden Sie username=sandbox und einen beliebigen API-Schlüssel.
Verwendung mit Claude Desktop
Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) hinzu:
{
"mcpServers": {
"mpesa": {
"command": "uvx",
"args": ["mpesa-mcp"],
"env": {
"MPESA_CONSUMER_KEY": "your_key",
"MPESA_CONSUMER_SECRET": "your_secret",
"MPESA_SHORTCODE": "174379",
"MPESA_PASSKEY": "your_passkey",
"MPESA_CALLBACK_URL": "https://yourdomain.com/mpesa/callback",
"MPESA_SANDBOX": "true",
"AT_USERNAME": "sandbox",
"AT_API_KEY": "your_at_key"
}
}
}
}Verwendung mit Claude Code
claude mcp add mpesa -- uvx mpesa-mcpSetzen Sie die Umgebungsvariablen in Ihrer Shell, bevor Sie claude ausführen.
Beispiel-Prompts
Sobald die Verbindung hergestellt ist, können Sie Ihren KI-Agenten fragen:
"Sende eine KES 500 STK-Push-Anfrage an +254712345678 für Bestellung #1234"
"Prüfe, ob die Zahlung QKL8ABC123 eingegangen ist"
"Sende eine SMS an diese 5 farmers mit dem heutigen Maispreis: [Liste]"
"Lade KES 50 Guthaben für unsere Außendienstmitarbeiter auf: [Liste der Nummern]"
Praxisbeispiele
Zahlungsabwicklung für Außendienstmitarbeiter
"Sende eine KES 300 STK-Push-Anfrage an jeden dieser 12 Außendienstmitarbeiter für die heutige Datenerfassung: [Liste]"
Der Agent löst 12 aufeinanderfolgende STK-Push-Anfragen aus, verfolgt jede checkout_request_id und fragt den Status zur Bestätigung ab – ohne dass Sie Code schreiben müssen.
Farmer-Alarm + Guthaben
"Sende eine SMS an diese 200 Farmer in Garissa, dass der Fluss steigt. Lade dann jedem 20 KES Guthaben auf, damit sie Berichte abgeben können."
Ein Prompt → 200 SMS-Nachrichten und 200 Guthabenaufladungen über Safaricom, Airtel und Telkom.
Zahlungsabgleich
"Prüfe, ob die Quittung OKL8M3B2HF eine erfolgreiche Zahlung war und wie hoch der Betrag war"
Nützlich für Support-Mitarbeiter, die Claude verwenden, um M-Pesa-Transaktionen in Echtzeit zu verifizieren.
Tool-Annotationen
Alle Tools deklarieren MCP-Tool-Annotationen, damit Clients Aufrufe entsprechend einschränken können:
Tool | readOnly | destructive | idempotent |
| ❌ | ✅ | ❌ |
| ✅ | ❌ | ✅ |
| ✅ | ❌ | ✅ |
| ❌ | ✅ | ❌ |
| ❌ | ✅ | ❌ |
Claude Desktop und andere MCP-Clients fordern eine Bestätigung an, bevor sie Zahlungs-, SMS- oder Guthabenoperationen auslösen.
Server-Erkennung
Funktionen werden über .well-known/mcp.json beworben – dem aufkommenden Standard für MCP-Server-Karten. Registries und Browser können die Tools dieses Servers indizieren, ohne eine Verbindung zu ihm herzustellen.
# Check capabilities
curl https://raw.githubusercontent.com/gabrielmahia/mpesa-mcp/main/.well-known/mcp.jsonTests und Genauigkeit
Der MCP-Ökosystem-Benchmark (CData, 2026) ergab, dass die meisten MCP-Server bei komplexen Abfragen zu 60–75 % genau sind – insbesondere bei stillen Fehlern bei Schreibvorgängen und teilweiser Parameteranwendung.
mpesa-mcp wurde gegen alle drei kenianischen Telefonnummernformate, Grenzwerte für Beträge und fehlende optionale Felder getestet:
pytest tests/ -v # run full suite
pytest tests/test_phone_formats.py # format normalization
pytest tests/test_boundary_amounts.py # min/max amount edge casesSchreibvorgänge (STK-Push, SMS, Guthaben) verfügen über eine explizite Validierung, bevor ein API-Aufruf getätigt wird.
Ökosystem-Kontext — Mojaloop + MCP
Mojaloop (finanziert von der Gates Foundation) kümmert sich um die Zahlungs-Interoperabilität – die Verbindung von Banken, mobilen Geldbörsen und Händlern über DFSPs in Ostafrika und darüber hinaus.
mpesa-mcp kümmert sich um die KI-Agenten-Tooling-Ebene – und ermöglicht es KI-Programmierassistenten, M-Pesa-Zahlungen programmgesteuert auszulösen und abzufragen.
Diese ergänzen sich:
Mojaloop: die Interoperabilitätsschienen zwischen Finanzanbietern
mpesa-mcp: die MCP-Schnittstellenebene, die KI-Agenten mit diesen Schienen verbindet
Siehe den Mojaloop-Dokumentationsbeitrag für mehr Informationen zu diesem Muster.
MCP vs. A2A — zwei verschiedene Protokolle
mpesa-mcp implementiert MCP (Model Context Protocol) – wie ein KI-Agent mit Tools spricht.
Es gibt ein ergänzendes Protokoll, A2A (Agent-to-Agent), das regelt, wie Agenten untereinander kommunizieren. Sie lösen unterschiedliche Probleme und arbeiten zusammen:
MCP: Ihr KI-Agent → mpesa-mcp → Daraja API / Africa's Talking
A2A: Orchestrator-Agent ↔ Zahlungs-Sub-Agent ↔ Benachrichtigungs-Sub-Agent
Für die meisten Integrationen benötigen Sie nur MCP. A2A wird relevant, wenn Sie Multi-Agenten-Systeme aufbauen, bei denen ein Zahlungs-Workflow mit anderen spezialisierten Agenten koordiniert wird.
Entwicklung
git clone https://github.com/gabrielmahia/mpesa-mcp
cd mpesa-mcp
pip install -e ".[dev]"
pytest tests/ -vSicherheit
Committen Sie keine API-Schlüssel. Verwenden Sie Umgebungsvariablen oder einen Secrets-Manager. Melden Sie Sicherheitslücken an: contact@aikungfu.dev
Lizenz
MIT — © 2026 Gabriel Mahia
Bleiben Sie auf dem Laufenden
Erhalten Sie Benachrichtigungen über neue Releases und Entwicklungen bei ostafrikanischen APIs: Updates abonnieren →
Oder beobachten Sie dieses Repository auf GitHub für Release-Benachrichtigungen.
Verwandte Pakete
Paket | Installation | Beschreibung |
| MCP-Server für Dürre-Intelligenz in Kenia | |
| Ostafrikanisches Civic-KI-SDK |
Zugehörige Pakete
Alle MIT · Alle Teil des ostafrikanischen Civic-KI-Stacks
Paket | Installation | Beschreibung |
| MCP-Server für Dürre-Intelligenz in Kenia | |
| Kenia-Gesundheitsdaten-MCP – NHIF, Einrichtungen, Mütter, Rechte | |
| Ostafrikanisches Civic-KI-SDK |
Gesamtportfolio: gabrielmahia.github.io
Available Tools
5 toolsairtime_sendSend AirtimeADestructive
Send airtime top-up to any MTN/Safaricom/Airtel/Vodafone subscriber. Common use: NGO field incentives, survey rewards, agent payouts. No real airtime sent in sandbox mode.
Inputs: phone (required), amount (required), currency_code. Returns: object
mpesa_stk_pushM-Pesa STK PushADestructive
Trigger an M-Pesa STK Push — sends a payment prompt to the customer's phone. The customer enters their M-Pesa PIN to complete payment. Returns a CheckoutRequestID to track the transaction with mpesa_stk_query. Async: use mpesa_stk_query after 10-30 seconds to check completion.
Inputs: phone (required), amount (required), account_ref (required), description. Returns: object
mpesa_stk_queryM-Pesa STK QueryARead-onlyIdempotent
Check the status of an STK Push request. Poll this 10-30 seconds after calling mpesa_stk_push. ResultCode 0 = success, 1032 = cancelled by user, 1037 = timed out.
Inputs: checkout_request_id (required). Returns: object
mpesa_transaction_statusM-Pesa Transaction StatusARead-onlyIdempotent
Query the status of any M-Pesa transaction by receipt number. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL env vars.
Inputs: transaction_id (required). Returns: object
sms_sendSend SMSADestructive
Send SMS to one or many recipients via Africa's Talking. Supports up to 1,000 recipients per call. Works across Kenya, Nigeria, Ghana, Tanzania, Uganda, and 15+ African markets. Returns per-recipient status and cost.
Inputs: message (required), recipients (required), sender_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct function: airtime sending, STK push initiation, STK push status query, transaction status by receipt, and SMS sending. There is no overlap or ambiguity.
Most tools follow a verb_noun or noun_verb pattern (e.g., airtime_send, sms_send, mpesa_stk_push), but mpesa_transaction_status lacks a verb, breaking the pattern slightly.
With 5 tools, the server is well-scoped for its purpose, covering core M-Pesa and SMS operations without being too few or too many.
The set covers STK push initiation/query and basic transaction status, but lacks airtime status, B2C/C2B transfers, or account balance queries, leaving notable gaps for a full M-Pesa integration.
Maintenance
Related MCP Connectors
South African MCP server for airtime, data, SMS, VAS, electricity, balance, and network lookup.
MCP Server for agents to onboard, pay, and provision services autonomously with InFlow
MCP server for Modern Treasury — payment orders, transactions, counterparties and ledgers.
MCP server for SuperPhone — contacts, conversations, tags and consent-based text messages.
Related MCP Servers
FlicenseNot gradedqualityDmaintenanceOpen-source MCP server that streamlines payment integration for AI agents and financial apps in Africa, providing unified tools for providers like M-Pesa.1-- FlicenseNot gradedqualityDmaintenanceAn experimental MCP server that lets AI agents interact with guarded payment workflows through typed tools, enabling safe agent-assisted payments with M-Pesa and mock Airtel Money.3-
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that integrates Safaricom's M-PESA Daraja API with Claude, enabling natural language payment processing and real-time transaction notifications.3-
- AlicenseNot gradedqualityDmaintenanceMCP server for the Lipila payment gateway, enabling AI agents to initiate mobile money and card collections, disburse funds, check transaction statuses, and verify webhook callbacks.1ISC