Skip to main content
Glama

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.

Tests PyPI License: MIT Glama Score Glama

mpesa-mcp MCP server

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

mpesa_stk_push

Löst eine STK-Push-Zahlungsaufforderung auf dem M-Pesa-Telefon des Kunden aus

mpesa_stk_query

Prüft den Status einer STK-Push-Anfrage

mpesa_transaction_status

Fragt jede M-Pesa-Transaktion anhand der Quittungsnummer ab

sms_send

Sendet SMS an 1–1.000 Empfänger in afrikanischen Netzwerken

airtime_send

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:

mpesa-mcp MCP server mpesa-mcp score

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

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

mpesa_stk_push

❌

✅

❌

mpesa_stk_query

✅

❌

✅

mpesa_transaction_status

✅

❌

✅

sms_send

❌

✅

❌

airtime_send

❌

✅

❌

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

Sicherheit

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

wapimaji-mcp

pip install wapimaji-mcp

MCP-Server für Dürre-Intelligenz in Kenia

civic-agent-kit

pip install civic-agent-kit

Ostafrikanisches Civic-KI-SDK

Zugehörige Pakete

Alle MIT · Alle Teil des ostafrikanischen Civic-KI-Stacks

Paket

Installation

Beschreibung

wapimaji-mcp

pip install wapimaji-mcp

MCP-Server für Dürre-Intelligenz in Kenia

kenya-health-mcp

pip install kenya-health-mcp

Kenia-Gesundheitsdaten-MCP – NHIF, Einrichtungen, Mütter, Rechte

civic-agent-kit

pip install civic-agent-kit

Ostafrikanisches Civic-KI-SDK

Gesamtportfolio: gabrielmahia.github.io

Available Tools

5 tools
airtime_sendSend AirtimeA
Destructive

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 PushA
Destructive

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 QueryA
Read-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 StatusA
Read-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 SMSA
Destructive

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

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Open-source MCP server that streamlines payment integration for AI agents and financial apps in Africa, providing unified tools for providers like M-Pesa.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      1
      ISC