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, comprobar el estado de las transacciones, enviar SMS y recargar saldo en más de 20 redes de telecomunicaciones africanas.

Por qué existe esto

M-Pesa procesa más transacciones al día que PayPal en África. Africa's Talking llega a usuarios en más de 20 países en teléfonos básicos mediante 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 kiswahili sin trabajo de integración personalizado.

mpesa-mcp cierra esa brecha con un pip install.

Herramientas

Cobertura

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

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

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 entorno de pruebas (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

• Clave de acceso 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 farmers con el precio del maíz de hoy: [lista]"

"Recarga 50 KES de saldo 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 consulta la confirmación, sin que tú tengas que escribir código.

Alerta a agricultores + recarga de saldo

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

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

Conciliación de pagos

"Comprueba si el recibo OKL8M3B2HF fue un pago exitoso y por qué cantidad 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:

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

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 de Kenia, 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, saldo) 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, monederos de dinero móvil y comercios a través de DFSPs 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 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 estás construyendo 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 subas claves API al repositorio. Usa variables de entorno o un gestor de secretos. Informa de vulnerabilidades a: contact@aikungfu.dev

Licencia

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