mpesa-mcp

mpesa-mcp

Servidor MCP para APIs fintech da África Oriental — M-Pesa (Safaricom Daraja) e Africa's Talking

Dê ao seu agente de IA a capacidade de acionar pagamentos M-Pesa, verificar o status de transações, enviar SMS e recarregar créditos em mais de 20 redes de telecomunicações africanas.

Testado com

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

Claude Sonnet 5 (lançado em 30 de junho de 2026) conclui fluxos de trabalho M-PESA de várias etapas sem parar no meio e autocorrige erros de chamada de ferramenta sem solicitação. Pontuação Terminal-Bench 80,4% vs 67,0% do Sonnet 4.6 — o benchmark mais análogo ao trabalho de agentes de pagamento.

Por que isso existe

O M-Pesa processa mais transações por dia do que o PayPal na África. A Africa's Talking alcança usuários em mais de 20 países em telefones básicos via SMS e USSD. Nenhum deles tem um servidor MCP.

Isso significa que todo agente de IA construído hoje — Claude, GPT, Gemini ou qualquer runtime compatível com MCP — não pode acionar um pagamento M-Pesa ou enviar um SMS em suaíli sem trabalho de integração personalizado.

mpesa-mcp fecha essa lacuna em um pip install.

Ferramentas

Ferramenta	Descrição
mpesa_stk_push	Aciona o prompt de pagamento STK Push no telefone M-Pesa do cliente
mpesa_stk_query	Verifica o status de uma solicitação STK Push
mpesa_transaction_status	Consulta qualquer transação M-Pesa pelo número do recibo
sms_send	Envia SMS para 1–1.000 destinatários em redes africanas
airtime_send	Envia recarga de crédito para qualquer assinante (KES, NGN, GHS, UGX, etc.)

Cobertura

• M-Pesa: Quênia (Safaricom Daraja v3) — STK Push, C2B, status de transação
• SMS/Crédito: Quênia, Nigéria, Gana, Tanzânia, Uganda, Ruanda, África do Sul e mais 15+ via Africa's Talking

Glama (MCP hospedado)

O mpesa-mcp está disponível como um servidor MCP hospedado no Glama:

Segurança — Conformidade com as Diretrizes MCP da NSA

mpesa-mcp foi atualizado em resposta à NSA CSI U/OO/6030316-26 (maio de 2026) — a Folha de Informações de Segurança Cibernética do Centro de Segurança de IA da NSA sobre segurança do Model Context Protocol.

A implementação abaixo documenta a conformidade com a estrutura de segurança MCP da NSA, controle por controle.

Controle da NSA	Implementação
Validação de parâmetros	Regex de telefone queniano ^254[17]\d{8}$ + limites de valor [1–150.000 KES]
Registro de auditoria	Registro estruturado por chamada de ferramenta; números de telefone com hash SHA-256
Ciclo de vida do token	Token OAuth armazenado em cache com expiração; renovação automática
Contenção de erros	Dicionários de erro estruturados; sem propagação de exceções brutas
Imposição de HTTPS	Todas as chamadas à API Daraja somente via HTTPS
Sem segredos codificados	Todas as credenciais via variáveis de ambiente

Consulte SECURITY.md para a tabela completa de conformidade.

Referência: NSA CSI_MCP_SECURITY.pdf — maio de 2026, SEM CLASSIFICAÇÃO

Instalação

pip install mpesa-mcp

Ou execute diretamente com uvx:

uvx mpesa-mcp

Configuração

Defina estas variáveis de ambiente antes de iniciar o 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

Credenciais de sandbox

Sandbox M-Pesa: https://developer.safaricom.co.ke — crie um aplicativo gratuito para obter credenciais de teste.

• Shortcode de teste: 174379
• Passkey de teste: bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919

Sandbox Africa's Talking: https://account.africastalking.com — use username=sandbox, qualquer chave de API.

Uso com Claude Desktop

Adicione ao ~/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 com Claude Code

claude mcp add mpesa -- uvx mpesa-mcp

Defina as variáveis de ambiente no seu shell antes de executar claude.

Exemplos de prompts

Depois de conectado, você pode pedir ao seu agente de IA:

"Envie STK Push de KES 500 para +254712345678 para o pedido #1234"

"Verifique se o pagamento QKL8ABC123 foi recebido"

"Envie um SMS para estes 50 agricultores com o preço do milho de hoje: [lista]"

"Recarregue KES 50 de crédito para nossos agentes de campo: [lista de números]"

Cenários do mundo real

Envio de pagamento para agentes de campo

"Envie STK Push de KES 300 para cada um destes 12 agentes de campo para a coleta de dados de hoje: [lista]"

O agente aciona 12 pushes STK sequenciais, rastreia cada checkout_request_id e verifica a confirmação — sem nenhum código seu.

Alerta para agricultores + crédito

"Envie SMS para estes 200 agricultores de Garissa que o rio está subindo. Depois, recarregue KES 20 de crédito para cada um para que possam ligar e reportar."

Um prompt → 200 mensagens SMS e 200 recargas de crédito em Safaricom, Airtel e Telkom.

Conciliação de pagamentos

"Verifique se o recibo OKL8M3B2HF foi um pagamento bem-sucedido e qual foi o valor"

Útil para agentes de suporte que usam o Claude para verificar transações M-Pesa em tempo real.

Anotações de ferramentas

Todas as ferramentas declaram anotações de ferramentas MCP para que os clientes possam controlar as chamadas adequadamente:

Ferramenta	readOnly	destrutiva	idempotente
mpesa_stk_push	❌	✅	❌
mpesa_stk_query	✅	❌	✅
mpesa_transaction_status	✅	❌	✅
sms_send	❌	✅	❌
airtime_send	❌	✅	❌

O Claude Desktop e outros clientes MCP solicitarão confirmação antes de acionar operações de pagamento, SMS ou crédito.

Descoberta de servidor

Os recursos são anunciados via .well-known/mcp.json — o padrão emergente de Cartões de Servidor MCP. Registros e navegadores podem indexar as ferramentas deste servidor sem se conectar a ele.

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

Testes e precisão

O benchmark do ecossistema MCP (CData, 2026) descobriu que a maioria dos servidores MCP é precisa em 60–75% das vezes em consultas complexas — particularmente falhas silenciosas em operações de escrita e aplicação parcial de parâmetros.

O mpesa-mcp é testado contra os três formatos de número de telefone queniano, valores de limite e campos opcionais ausentes:

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

Operações de escrita (STK push, SMS, crédito) têm validação explícita antes de qualquer chamada de API ser feita.

Contexto do ecossistema — Mojaloop + MCP

Mojaloop (financiado pela Fundação Gates) lida com interoperabilidade de pagamentos — conectando bancos, carteiras de dinheiro móvel e comerciantes entre DFSPs na África Oriental e além.

mpesa-mcp lida com a camada de ferramentas de agente de IA — permitindo que assistentes de codificação de IA acionem e consultem pagamentos M-Pesa programaticamente.

Estes são complementares:

• Mojaloop: os trilhos de interoperabilidade entre provedores financeiros
• mpesa-mcp: a camada de interface MCP que conecta agentes de IA a esses trilhos

Consulte a contribuição de documentação do Mojaloop para mais sobre esse padrão.

MCP vs A2A — dois protocolos diferentes

O mpesa-mcp implementa MCP (Model Context Protocol) — como um agente de IA conversa com ferramentas.

Existe um protocolo complementar, A2A (Agent-to-Agent), que lida com como os agentes conversam entre si. Eles resolvem problemas diferentes e trabalham juntos:

• MCP: Seu agente de IA → mpesa-mcp → API Daraja / Africa's Talking
• A2A: Agente orquestrador ↔ subagente de pagamento ↔ subagente de notificação

Para a maioria das integrações, você só precisa de MCP. A2A se torna relevante quando você está construindo sistemas multiagentes onde um fluxo de trabalho de pagamento coordena com outros agentes especializados.

---

Desenvolvimento

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

Segurança

Não faça commit de chaves de API. Use variáveis de ambiente ou um gerenciador de segredos.
Reporte vulnerabilidades para: contact@aikungfu.dev

Contexto de pesquisa

Benchmark do ecossistema MCP (CData, 2026): A maioria dos servidores MCP atinge 60-75% de precisão em consultas complexas. O mpesa-mcp inclui validação explícita e verificação de limites para superar essa linha de base.

Precisão de IA em suaíli (arXiv:2509.04516, 2025): Modelos de IA produzem 4× mais erros em suaíli do que em inglês. As descrições de ferramentas nativas em suaíli do mpesa-mcp são projetadas para minimizar essa lacuna para usuários que falam suaíli, eliminando a etapa de tradução na seleção de ferramentas.

Pesquisa de segurança MCP (arXiv:2603.18063, arXiv:2603.21642, 2026): Injeção de prompt via descrições de ferramentas é o principal vetor de ataque MCP. O mpesa-mcp mitiga isso por meio de descrições de ferramentas estáticas e versionadas e validação rigorosa de entrada.

Infraestrutura relacionada:

• wapimaji-mcp — MCP de água/seca do Quênia
• civic-agent-kit — MCP de dados cívicos do Quênia
• swahili-health-mcp — MCP de dados de saúde DHIS2 do Quênia
• kenya-legal-rag — MCP de corpus jurídico do Quênia
• Portfólio completo: gabrielmahia.github.io

Licença

MIT — © 2026 Gabriel Mahia

Mantenha-se atualizado

Receba notificações de novos lançamentos e desenvolvimentos de APIs da África Oriental: Inscreva-se para atualizações →

Ou acompanhe este repositório no GitHub para notificações de lançamentos.

Pacotes irmãos

Pacote	Instalação	Descrição
wapimaji-mcp	pip install wapimaji-mcp	Servidor MCP de inteligência de seca do Quênia
civic-agent-kit	pip install civic-agent-kit	SDK de IA cívica da África Oriental

Pacotes relacionados

Todos MIT · Todos parte da pilha de IA cívica da África Oriental

Pacote	Instalação	Descrição
wapimaji-mcp	pip install wapimaji-mcp	Servidor MCP de inteligência de seca do Quênia
kenya-health-mcp	pip install kenya-health-mcp	MCP de dados de saúde do Quênia — NHIF, instalações, saúde materna, direitos
civic-agent-kit	pip install civic-agent-kit	SDK de IA cívica da África Oriental

Portfólio completo: gabrielmahia.github.io

Parte da Pilha de Coordenação da África Oriental

Este servidor MCP é uma das 32 ferramentas na infraestrutura de coordenação do Quênia. Conecte-o ao africa-coord-bus — o barramento de eventos de coordenação que roteia sinais entre domínios automaticamente.

pip install africa-coord-bus

Todos os 32 servidores: pypi.org/user/gmahia Demonstração ao vivo: coord-cascade-demo

IP e Colaboração

Licenciado sob MIT. Feedback apenas via Issues do GitHub — pull requests não são aceitos. Os dados de demonstração são rotulados como DEMO e não são adequados para decisões operacionais. Política completa: docs/architecture/IP_POLICY.md. Relatórios de segurança: consulte SECURITY.md.

Parte da pilha de coordenação da África Oriental

• Instalação e execução: pip install reli-cli && reli list — 33 servidores MCP no Registro MCP oficial sob io.github.gabrielmahia
• Avalie qualquer modelo em tarefas de agente em suaíli: kipimo · dataset · leaderboard
• Coordene entre servidores: africa-coord-bus — barramento de eventos offline-first com tabela de roteamento do Quênia integrada
• Datasets: huggingface.co/gmahia · Hub de documentação: nairobi-stack

Agnóstico de modelo por design: APIs fechadas, modelos de peso aberto e pequenos modelos destilados são todos cidadãos de primeira classe.