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 activar pagos M-Pesa, consultar el estado de transacciones, enviar SMS y recargar tiempo aire en más de 20 redes de telecomunicaciones africanas.
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 |
| Activa una solicitud de pago STK Push en el teléfono M-Pesa del cliente |
| Comprueba el estado de una solicitud STK Push |
| Consulta cualquier transacción de M-Pesa por número de recibo |
| Envía SMS a entre 1 y 1.000 destinatarios en redes africanas |
| 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:
Instalación
pip install mpesa-mcpO ejecútalo directamente con uvx:
uvx mpesa-mcpConfiguració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_keyCredenciales 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:
174379Passkey 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-mcpEstablece 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 |
| ❌ | ✅ | ❌ |
| ✅ | ❌ | ✅ |
| ✅ | ❌ | ✅ |
| ❌ | ✅ | ❌ |
| ❌ | ✅ | ❌ |
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.jsonPruebas 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 casesLas 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/ -vSeguridad
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 |
| Servidor MCP de inteligencia sobre sequías en Kenia | |
| 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 |
| Servidor MCP de inteligencia sobre sequías en Kenia | |
| MCP de datos de salud de Kenia — NHIF, instalaciones, salud materna, derechos | |
| SDK de IA cívica de África Oriental |
Portafolio completo: gabrielmahia.github.io
Available Tools
5 toolsairtime_sendSend AirtimeADestructive
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 PushADestructive
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 QueryARead-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 StatusARead-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 SMSADestructive
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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
South African MCP server for airtime, data, SMS, VAS, electricity, balance, and network lookup.
MCP Server for agents to onboard, pay, and provision services autonomously with InFlow
MCP server for Modern Treasury — payment orders, transactions, counterparties and ledgers.
MCP server for SuperPhone — contacts, conversations, tags and consent-based text messages.
Related MCP Servers
FlicenseNot gradedqualityDmaintenanceOpen-source MCP server that streamlines payment integration for AI agents and financial apps in Africa, providing unified tools for providers like M-Pesa.1-- FlicenseNot gradedqualityDmaintenanceAn experimental MCP server that lets AI agents interact with guarded payment workflows through typed tools, enabling safe agent-assisted payments with M-Pesa and mock Airtel Money.3-
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseCqualityDmaintenanceAn 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.7465 npm1MIT