Skip to main content
Glama

mpesa-mcp

Servidor MCP para APIs fintech de África Oriental: M-Pesa (Safaricom Daraja) y Africa's Talking

Dale a tu agente de IA la capacidad de activar pagos M-Pesa, consultar el estado de transacciones, enviar SMS y recargar tiempo aire en más de 20 redes de telecomunicaciones africanas.

Tests PyPI License: MIT Glama Score Glama

mpesa-mcp MCP server

Por qué existe esto

M-Pesa procesa más transacciones por día que PayPal en África. Africa's Talking llega a usuarios en más de 20 países en teléfonos básicos a través de SMS y USSD. Ninguno tiene un servidor MCP.

Esto significa que cualquier agente de IA construido hoy —Claude, GPT, Gemini o cualquier entorno de ejecución compatible con MCP— no puede activar un pago M-Pesa o enviar un SMS en suajili sin trabajo de integración personalizado.

mpesa-mcp cierra esa brecha con un pip install.

Related MCP server: M-Pesa MCP Server

Herramientas

Herramienta

Descripción

mpesa_stk_push

Activa una solicitud de pago STK Push en el teléfono M-Pesa del cliente

mpesa_stk_query

Comprueba el estado de una solicitud STK Push

mpesa_transaction_status

Consulta cualquier transacción de M-Pesa por número de recibo

sms_send

Envía SMS a entre 1 y 1.000 destinatarios en redes africanas

airtime_send

Envía recarga de tiempo aire a cualquier suscriptor (KES, NGN, GHS, UGX, etc.)

Cobertura

  • M-Pesa: Kenia (Safaricom Daraja v3) — STK Push, C2B, estado de transacción

  • SMS/Tiempo aire: Kenia, Nigeria, Ghana, Tanzania, Uganda, Ruanda, Sudáfrica y más de 15 adicionales a través de Africa's Talking

Glama (MCP alojado)

mpesa-mcp está disponible como servidor MCP alojado en Glama:

mpesa-mcp MCP server mpesa-mcp score

Instalación

pip install mpesa-mcp

O ejecútalo directamente con uvx:

uvx mpesa-mcp

Configuración

Establece estas variables de entorno antes de iniciar el servidor:

# 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

Credenciales de Sandbox

M-Pesa sandbox: https://developer.safaricom.co.ke — crea una aplicación gratuita para obtener credenciales de prueba.

  • Código corto de prueba: 174379

  • Passkey de prueba: bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919

Africa's Talking sandbox: https://account.africastalking.com — usa username=sandbox, cualquier clave API.

Uso con Claude Desktop

Añádelo a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "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"
      }
    }
  }
}

Uso con Claude Code

claude mcp add mpesa -- uvx mpesa-mcp

Establece las variables de entorno en tu shell antes de ejecutar claude.

Ejemplos de prompts

Una vez conectado, puedes pedirle a tu agente de IA:

"Envía un STK Push de 500 KES al +254712345678 para el pedido #1234"

"Comprueba si se ha recibido el pago QKL8ABC123"

"Envía un SMS a estos 5 agricultores con el precio del maíz de hoy: [lista]"

"Recarga 50 KES de tiempo aire para nuestros agentes de campo: [lista de números]"

Escenarios del mundo real

Envío de pagos a agentes de campo

"Envía un STK Push de 300 KES a cada uno de estos 12 agentes de campo para la recolección de datos de hoy: [lista]"

El agente activa 12 solicitudes STK secuenciales, rastrea cada checkout_request_id y sondea para obtener confirmación, sin que tú escribas código.

Alerta a agricultores + tiempo aire

"Envía un SMS a estos 200 agricultores de Garissa avisando que el río está subiendo. Luego recarga 20 KES de tiempo aire a cada uno para que puedan llamar e informar."

Un prompt → 200 mensajes SMS y 200 recargas de tiempo aire en Safaricom, Airtel y Telkom.

Conciliación de pagos

"Comprueba si el recibo OKL8M3B2HF fue un pago exitoso y por cuánto fue"

Útil para agentes de soporte que usan Claude para verificar transacciones de M-Pesa en tiempo real.

Anotaciones de herramientas

Todas las herramientas declaran anotaciones de herramientas MCP para que los clientes puedan gestionar las llamadas adecuadamente:

Herramienta

readOnly

destructive

idempotent

mpesa_stk_push

❌

✅

❌

mpesa_stk_query

✅

❌

✅

mpesa_transaction_status

✅

❌

✅

sms_send

❌

✅

❌

airtime_send

❌

✅

❌

Claude Desktop y otros clientes MCP solicitarán confirmación antes de activar operaciones de pago, SMS o tiempo aire.

Descubrimiento del servidor

Las capacidades se anuncian a través de .well-known/mcp.json, el estándar emergente de tarjetas de servidor MCP. Los registros y navegadores pueden indexar las herramientas de este servidor sin conectarse a él.

# Check capabilities
curl https://raw.githubusercontent.com/gabrielmahia/mpesa-mcp/main/.well-known/mcp.json

Pruebas y precisión

El benchmark del ecosistema MCP (CData, 2026) encontró que la mayoría de los servidores MCP son precisos entre el 60% y el 75% de las veces en consultas complejas, particularmente en fallos silenciosos en operaciones de escritura y aplicación parcial de parámetros.

mpesa-mcp se prueba contra los tres formatos de números de teléfono kenianos, valores límite de cantidad y campos opcionales faltantes:

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

Las operaciones de escritura (STK push, SMS, tiempo aire) tienen una validación explícita antes de realizar cualquier llamada a la API.

Contexto del ecosistema — Mojaloop + MCP

Mojaloop (financiado por la Fundación Gates) maneja la interoperabilidad de pagos, conectando bancos, billeteras de dinero móvil y comerciantes a través de DFSP en África Oriental y más allá.

mpesa-mcp maneja la capa de herramientas para agentes de IA, permitiendo que los asistentes de codificación de IA activen y consulten pagos de M-Pesa mediante programación.

Estos son complementarios:

  • Mojaloop: los rieles de interoperabilidad entre proveedores financieros

  • mpesa-mcp: la capa de interfaz MCP que conecta a los agentes de IA con esos rieles

Consulta la contribución a la documentación de Mojaloop para obtener más información sobre este patrón.

MCP vs A2A — dos protocolos diferentes

mpesa-mcp implementa MCP (Model Context Protocol), cómo un agente de IA habla con las herramientas.

Existe un protocolo complementario, A2A (Agent-to-Agent), que maneja cómo los agentes hablan entre sí. Resuelven problemas diferentes y trabajan juntos:

  • MCP: Tu agente de IA → mpesa-mcp → API Daraja / Africa's Talking

  • A2A: Agente orquestador ↔ subagente de pago ↔ subagente de notificación

Para la mayoría de las integraciones solo necesitas MCP. A2A se vuelve relevante cuando construyes sistemas multi-agente donde un flujo de trabajo de pago se coordina con otros agentes especializados.


Desarrollo

git clone https://github.com/gabrielmahia/mpesa-mcp
cd mpesa-mcp
pip install -e ".[dev]"
pytest tests/ -v

Seguridad

No confirmes claves API. Usa variables de entorno o un gestor de secretos. Informa de vulnerabilidades a: contact@aikungfu.dev

Licencia

MIT — © 2026 Gabriel Mahia

Mantente actualizado

Recibe notificaciones de nuevos lanzamientos y desarrollos de APIs en África Oriental: Suscríbete a las actualizaciones →

O sigue este repositorio en GitHub para recibir notificaciones de lanzamientos.

Paquetes hermanos

Paquete

Instalación

Descripción

wapimaji-mcp

pip install wapimaji-mcp

Servidor MCP de inteligencia sobre sequías en Kenia

civic-agent-kit

pip install civic-agent-kit

SDK de IA cívica de África Oriental

Paquetes relacionados

Todos MIT · Todos parte de la pila de IA cívica de África Oriental

Paquete

Instalación

Descripción

wapimaji-mcp

pip install wapimaji-mcp

Servidor MCP de inteligencia sobre sequías en Kenia

kenya-health-mcp

pip install kenya-health-mcp

MCP de datos de salud de Kenia — NHIF, instalaciones, salud materna, derechos

civic-agent-kit

pip install civic-agent-kit

SDK de IA cívica de África Oriental

Portafolio completo: 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

    ActivityNo data
    ResponsivenessOutdated 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
      C
      quality
      D
      maintenance
      An MCP server that enables AI assistants to interact with Interswitch APIs for payments, transfers, VAS, cardless paycodes, Transaction Search, Card 360, lending, payouts, agency banking, and fintech card-processing utilities.
      74
      65 npm
      1
      MIT