mpesa-mcp

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 iniciar pagos M-Pesa, consultar el estado de transacciones, enviar SMS y recargar saldo en más de 20 redes de telecomunicaciones africanas.

Probado con

claude-sonnet-5  (recommended — call get_model_hint() for guidance)
claude-opus-4-8  (for highest-accuracy compliance reasoning)

Claude Sonnet 5 (lanzado el 30 de junio de 2026) completa flujos de trabajo M-PESA de varios pasos sin detenerse a mitad de camino y autocorrige errores de llamadas a herramientas sin necesidad de indicaciones adicionales. Puntuación Terminal-Bench del 80,4 % frente al 67,0 % de Sonnet 4.6 — el benchmark más análogo al trabajo de agentes de pago.

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 con teléfonos básicos mediante SMS y USSD. Ninguno de los dos tiene un servidor MCP.

Esto significa que todo agente de IA construido hoy — Claude, GPT, Gemini o cualquier runtime compatible con MCP — no puede iniciar un pago M-Pesa ni enviar un SMS en kiswahili sin trabajo de integración personalizado.

mpesa-mcp cierra esa brecha en un solo pip install.

Herramientas

Herramienta	Descripción
mpesa_stk_push	Activa la solicitud de pago STK Push en el teléfono M-Pesa del cliente
mpesa_stk_query	Consulta el estado de una solicitud STK Push
mpesa_transaction_status	Consulta cualquier transacción 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 saldo a cualquier suscriptor (KES, NGN, GHS, UGX, etc.)

Cobertura

• M-Pesa: Kenia (Safaricom Daraja v3) — STK Push, C2B, estado de transacciones
• 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

Glama (MCP alojado)

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

Seguridad — Cumplimiento de las directrices MCP de la NSA

mpesa-mcp se actualizó en respuesta a la NSA CSI U/OO/6030316-26 (mayo de 2026) — la hoja informativa de ciberseguridad del Centro de Seguridad de IA de la NSA sobre la seguridad del Model Context Protocol.

La implementación que se presenta a continuación documenta el cumplimiento del marco de seguridad MCP de la NSA, control por control.

Control de la NSA	Implementación
Validación de parámetros	Regex de teléfonos kenianos ^254[17]\d{8}$ + límites de importe [1–150.000 KES]
Registro de auditoría	Registro estructurado por cada llamada a herramienta; números de teléfono con hash SHA-256
Ciclo de vida de tokens	Token OAuth almacenado en caché con caducidad; renovación automática
Contención de errores	Diccionarios de error estructurados; sin propagación de excepciones sin procesar
Aplicación de HTTPS	Todas las llamadas a la API de Daraja solo mediante HTTPS
Sin secretos codificados	Todas las credenciales mediante variables de entorno

Consulta SECURITY.md para ver la tabla completa de cumplimiento.

Referencia: NSA CSI_MCP_SECURITY.pdf — mayo de 2026, NO CLASIFICADO

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

Sandbox de M-Pesa: 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

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

Uso con Claude Desktop

Añade 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 indicaciones

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

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

"Comprueba si se ha recibido el pago QKL8ABC123"

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

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

Escenarios del mundo real

Despacho de pagos a agentes de campo

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

El agente activa 12 STK Push secuenciales, realiza el seguimiento de cada checkout_request_id y consulta la confirmación — sin ningún código por tu parte.

Alerta a agricultores + saldo

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

Una sola indicación → 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 cuánto fue"

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

Anotaciones de herramientas

Todas las herramientas declaran anotaciones de herramientas MCP para que los clientes puedan controlar las llamadas de forma adecuada:

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 saldo.

Descubrimiento del servidor

Las capacidades se anuncian mediante .well-known/mcp.json — el estándar emergente de MCP Server Cards. Los registros y navegadores pueden indexar las herramientas de este servidor sin necesidad de 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 — en particular, fallos silenciosos en operaciones de escritura y aplicación parcial de parámetros.

mpesa-mcp se prueba con los tres formatos de número de teléfono keniano, valores límite de importe 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 validación explícita antes de realizar cualquier llamada a la API.

Contexto del ecosistema — Mojaloop + MCP

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

mpesa-mcp gestiona la capa de herramientas para agentes de IA — permitiendo que los asistentes de codificación de IA activen y consulten pagos M-Pesa de forma programática.

Son complementarios:

• Mojaloop: los raíles de interoperabilidad entre proveedores financieros
• mpesa-mcp: la capa de interfaz MCP que conecta a los agentes de IA con esos raíles

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 gestiona cómo los agentes hablan entre sí. Resuelven problemas diferentes y funcionan juntos:

• MCP: Tu agente de IA → mpesa-mcp → API de Daraja / Africa's Talking
• A2A: Agente orquestador ↔ subagente de pagos ↔ subagente de notificaciones

Para la mayoría de las integraciones solo necesitas MCP. A2A cobra relevancia cuando construyes sistemas multiagente donde un flujo de trabajo de pagos 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 de API. Usa variables de entorno o un gestor de secretos.
Reporta vulnerabilidades a: contact@aikungfu.dev

Contexto de investigación

Benchmark del ecosistema MCP (CData, 2026): La mayoría de los servidores MCP alcanzan una precisión del 60-75 % en consultas complejas. mpesa-mcp incluye validación explícita y comprobación de límites para superar esta línea base.

Precisión de la IA en suajili (arXiv:2509.04516, 2025): Los modelos de IA producen 4× más errores en suajili que en inglés. Las descripciones de herramientas nativas en suajili de mpesa-mcp están diseñadas para minimizar esta brecha para los usuarios de habla suajili al eliminar el paso de traducción en la selección de herramientas.

Investigación de seguridad MCP (arXiv:2603.18063, arXiv:2603.21642, 2026): La inyección de indicaciones a través de descripciones de herramientas es el principal vector de ataque de MCP. mpesa-mcp mitiga esto mediante descripciones de herramientas estáticas y versionadas y una validación estricta de entrada.

Infraestructura relacionada:

• wapimaji-mcp — MCP de agua/sequía de Kenia
• civic-agent-kit — MCP de datos cívicos de Kenia
• swahili-health-mcp — MCP de datos de salud DHIS2 de Kenia
• kenya-legal-rag — MCP del corpus legal de Kenia
• Portafolio completo: gabrielmahia.github.io

Licencia

MIT — © 2026 Gabriel Mahia

Mantente al día

Recibe notificaciones de nuevos lanzamientos y novedades de APIs de Á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 de sequía en Kenia
civic-agent-kit	pip install civic-agent-kit	SDK de IA cívica de África Oriental

Paquetes relacionados

Todos MIT · Todos parte del stack de IA cívica de África Oriental

Paquete	Instalación	Descripción
wapimaji-mcp	pip install wapimaji-mcp	Servidor MCP de inteligencia de sequía 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

Parte del East Africa Coordination Stack

Este servidor MCP es una de las 32 herramientas de la infraestructura de coordinación de Kenia. Conéctalo a africa-coord-bus — el bus de eventos de coordinación que enruta señales entre dominios automáticamente.

pip install africa-coord-bus

Los 32 servidores: pypi.org/user/gmahia Demo en vivo: coord-cascade-demo

Propiedad intelectual y colaboración

Licencia MIT. Comentarios únicamente a través de GitHub Issues — no se aceptan pull requests. Los datos de demostración están etiquetados como DEMO y no son adecuados para decisiones operativas. Política completa: docs/architecture/IP_POLICY.md. Reportes de seguridad: consulta SECURITY.md.

Parte del stack de coordinación de África Oriental

• Instalación y ejecución: pip install reli-cli && reli list — 33 servidores MCP en el Registro oficial de MCP bajo io.github.gabrielmahia
• Evalúa cualquier modelo en tareas de agentes en suajili: kipimo · dataset · leaderboard
• Coordina entre servidores: africa-coord-bus — bus de eventos offline-first con tabla de enrutamiento de Kenia integrada
• Datasets: huggingface.co/gmahia · Centro de documentación: nairobi-stack

Independiente del modelo por diseño: las APIs cerradas, los modelos de peso abierto y los modelos pequeños destilados son todos ciudadanos de primera clase.