mpesa-mcp

동아프리카 핀테크 API를 위한 MCP 서버 — M-Pesa (Safaricom Daraja) 및 Africa's Talking 지원

AI 에이전트가 M-Pesa 결제를 트리거하고, 거래 상태를 확인하며, 20개 이상의 아프리카 통신 네트워크에 SMS를 보내고 통신비를 충전할 수 있는 기능을 제공합니다.

이 서버가 필요한 이유

M-Pesa는 아프리카에서 PayPal보다 더 많은 일일 거래를 처리합니다. Africa's Talking은 SMS와 USSD를 통해 20개국 이상의 기본 휴대폰 사용자에게 도달합니다. 하지만 이들 중 MCP 서버를 지원하는 곳은 없습니다.

즉, 오늘날 구축된 모든 AI 에이전트(Claude, GPT, Gemini 또는 MCP 호환 런타임)는 별도의 맞춤형 통합 작업 없이는 M-Pesa 결제를 트리거하거나 스와힐리어 SMS를 보낼 수 없습니다.

mpesa-mcp는 pip install 한 번으로 그 격차를 해소합니다.

도구

지원 범위

• M-Pesa: 케냐 (Safaricom Daraja v3) — STK Push, C2B, 거래 상태 확인

• SMS/통신비: 케냐, 나이지리아, 가나, 탄자니아, 우간다, 르완다, 남아프리카 공화국 등 Africa's Talking을 통한 15개국 이상 지원

설치

pip install mpesa-mcp

또는 uvx를 사용하여 직접 실행:

uvx mpesa-mcp

설정

서버를 시작하기 전에 다음 환경 변수를 설정하세요:

# 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

샌드박스 자격 증명

M-Pesa 샌드박스: https://developer.safaricom.co.ke — 무료 앱을 생성하여 테스트 자격 증명을 받으세요.

• 테스트 단축 코드: 174379

• 테스트 패스키: bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919

Africa's Talking 샌드박스: https://account.africastalking.com — username=sandbox와 임의의 API 키를 사용하세요.

Claude Desktop에서 사용하기

~/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"
      }
    }
  }
}

Claude Code에서 사용하기

claude mcp add mpesa -- uvx mpesa-mcp

claude를 실행하기 전에 셸에서 환경 변수를 설정하세요.

예시 프롬프트

연결되면 AI 에이전트에게 다음과 같이 요청할 수 있습니다:

"주문 번호 #1234에 대해 +254712345678 번호로 KES 500 STK Push를 보내줘"

"결제 번호 QKL8ABC123이 수신되었는지 확인해줘"

"오늘의 옥수수 가격을 이 5명의 농부들에게 SMS로 보내줘: [목록]"

"현장 요원들에게 KES 50 통신비를 충전해줘: [번호 목록]"

실제 활용 시나리오

현장 요원 결제 지급

"오늘 데이터 수집을 위해 이 12명의 현장 요원 각각에게 KES 300 STK Push를 보내줘: [목록]"

에이전트가 12개의 STK Push를 순차적으로 트리거하고, 각 checkout_request_id를 추적하며, 확인을 위해 폴링합니다. 사용자가 별도의 코드를 작성할 필요가 없습니다.

농부 알림 + 통신비 충전

"강물이 불어나고 있다는 내용을 가리사(Garissa) 농부 200명에게 SMS로 보내줘. 그런 다음 보고를 할 수 있도록 각각 KES 20 통신비를 충전해줘."

프롬프트 하나로 Safaricom, Airtel, Telkom 전역에 200개의 SMS 메시지와 200개의 통신비 충전이 이루어집니다.

결제 대조

"영수증 OKL8M3B2HF가 성공적인 결제였는지, 금액은 얼마였는지 확인해줘"

Claude를 사용하여 실시간으로 M-Pesa 거래를 확인해야 하는 지원 담당자에게 유용합니다.

도구 주석

모든 도구는 MCP 도구 주석을 선언하여 클라이언트가 호출을 적절하게 제어할 수 있도록 합니다:

Claude Desktop 및 기타 MCP 클라이언트는 결제, SMS 또는 통신비 작업을 트리거하기 전에 확인을 요청합니다.

서버 검색

기능은 새로운 MCP 서버 카드 표준인 .well-known/mcp.json을 통해 광고됩니다. 레지스트리와 브라우저는 서버에 연결하지 않고도 이 서버의 도구를 인덱싱할 수 있습니다.

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

테스트 및 정확도

MCP 생태계 벤치마크(CData, 2026)에 따르면 대부분의 MCP 서버는 복잡한 쿼리에서 60~75%의 정확도를 보이며, 특히 쓰기 작업에서의 조용한 실패와 부분적인 매개변수 적용 문제가 발견되었습니다.

mpesa-mcp는 세 가지 케냐 전화번호 형식, 경계 금액 값, 누락된 선택적 필드에 대해 테스트되었습니다:

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

쓰기 작업(STK push, SMS, 통신비)은 API 호출이 이루어지기 전에 명시적인 유효성 검사를 거칩니다.

생태계 맥락 — Mojaloop + MCP

Mojaloop(게이츠 재단 지원)는 결제 상호운용성을 처리하며, 동아프리카 및 그 외 지역의 DFSP 간에 은행, 모바일 머니 지갑, 가맹점을 연결합니다.

mpesa-mcp는 AI 에이전트 도구 계층을 처리하며, AI 코딩 어시스턴트가 프로그래밍 방식으로 M-Pesa 결제를 트리거하고 조회할 수 있도록 합니다.

이 둘은 상호 보완적입니다:

• Mojaloop: 금융 제공자 간의 상호운용성 레일

• mpesa-mcp: AI 에이전트를 해당 레일에 연결하는 MCP 인터페이스 계층

이 패턴에 대한 자세한 내용은 Mojaloop 문서 기여를 참조하세요.

MCP vs A2A — 두 가지 다른 프로토콜

mpesa-mcp는 MCP(Model Context Protocol)를 구현합니다. 이는 AI 에이전트가 도구와 대화하는 방식입니다.

에이전트가 서로 대화하는 방식을 처리하는 보완 프로토콜인 A2A(Agent-to-Agent)가 있습니다. 이들은 서로 다른 문제를 해결하며 함께 작동합니다:

• MCP: AI 에이전트 → mpesa-mcp → Daraja API / Africa's Talking

• A2A: 오케스트레이터 에이전트 ↔ 결제 하위 에이전트 ↔ 알림 하위 에이전트

대부분의 통합에는 MCP만 있으면 됩니다. A2A는 결제 워크플로가 다른 전문 에이전트와 조정되는 다중 에이전트 시스템을 구축할 때 관련이 있습니다.

개발

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

보안

API 키를 커밋하지 마세요. 환경 변수나 보안 관리자를 사용하세요. 취약점 보고: contact@aikungfu.dev

라이선스

CC BY-NC-ND 4.0 — © 2026 Gabriel Mahia

업데이트 소식

새로운 릴리스 및 동아프리카 API 개발 소식을 받아보세요: 업데이트 구독하기 →

또는 GitHub에서 이 저장소를 팔로우하여 릴리스 알림을 받으세요.