mpesa-mcp

MCP-Server für ostafrikanische Fintech-APIs – M-Pesa (Safaricom Daraja) und Africa's Talking

Ermöglichen Sie Ihrem KI-Agenten, M-Pesa-Zahlungen auszulösen, 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 via 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.

Tools

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 via Africa's Talking

Installation

pip install mpesa-mcp

Oder führen Sie es direkt mit uvx aus:

uvx mpesa-mcp

Konfiguration

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_key

Sandbox-Anmeldedaten

M-Pesa Sandbox: https://developer.safaricom.co.ke – erstellen Sie eine kostenlose App, um Test-Anmeldedaten zu erhalten.

• Test-Kurzwahlnummer: 174379

• Test-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-mcp

Setzen 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]"

Praxis-Szenarien

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 die Bestätigung ab – ohne dass Sie Code schreiben müssen.

Farmer-Benachrichtigung + Guthaben

"Sende eine SMS an diese 200 Farmer in Garissa, dass der Fluss steigt. Lade dann jeweils KES 20 Guthaben auf, damit sie Berichte telefonisch durchgeben können."

Ein Prompt → 200 SMS-Nachrichten und 200 Guthaben-Aufladungen ü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:

Claude Desktop und andere MCP-Clients fordern eine Bestätigung an, bevor Zahlungs-, SMS- oder Guthaben-Operationen ausgelöst werden.

Server-Erkennung

Funktionen werden über .well-known/mcp.json beworben – den aufkommenden MCP Server Cards-Standard. 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.json

Tests 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 wird 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 cases

Schreibvorgänge (STK-Push, SMS, Guthaben) verfügen über eine explizite Validierung, bevor ein API-Aufruf getätigt wird.

Ökosystem-Kontext – Mojaloop + MCP

Mojaloop (finanziert durch die 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 – es ermöglicht KI-Programmierassistenten, M-Pesa-Zahlungen programmgesteuert auszulösen und abzufragen.

Diese ergänzen sich:

• Mojaloop: die Interoperabilitäts-Schienen zwischen Finanzanbietern

• mpesa-mcp: die MCP-Schnittstellenebene, die KI-Agenten mit diesen Schienen verbindet

Weitere Informationen zu diesem Muster finden Sie im Mojaloop-Dokumentationsbeitrag.

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 sprechen. 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/ -v

Sicherheit

Committen Sie keine API-Schlüssel. Verwenden Sie Umgebungsvariablen oder einen Secrets-Manager. Melden Sie Sicherheitslücken an: contact@aikungfu.dev

Lizenz

CC BY-NC-ND 4.0 – © 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.