mpesa-mcp

MCP-сервер для финтех-API Восточной Африки — M-Pesa (Safaricom Daraja) и Africa's Talking

Предоставьте своему ИИ-агенту возможность инициировать платежи M-Pesa, проверять статус транзакций, отправлять SMS и пополнять баланс в 20+ африканских телекоммуникационных сетях.

Зачем это нужно

M-Pesa обрабатывает больше транзакций в день, чем PayPal в Африке. Africa's Talking охватывает пользователей в 20+ странах на простых телефонах через SMS и USSD. Ни у одного из них нет MCP-сервера.

Это означает, что любой ИИ-агент, созданный сегодня — Claude, GPT, Gemini или любая среда выполнения, совместимая с MCP, — не может инициировать платеж M-Pesa или отправить SMS на суахили без дополнительной интеграции.

mpesa-mcp устраняет этот пробел с помощью одной команды pip install.

Инструменты

Покрытие

• M-Pesa: Кения (Safaricom Daraja v3) — STK Push, C2B, статус транзакции

• SMS/Airtime: Кения, Нигерия, Гана, Танзания, Уганда, Руанда, Южная Африка и еще 15+ стран через Africa's Talking

Установка

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

Песочница (Sandbox)

M-Pesa sandbox: https://developer.safaricom.co.ke — создайте бесплатное приложение, чтобы получить тестовые учетные данные.

• Тестовый короткий код: 174379

• Тестовый пароль (passkey): bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919

Africa's Talking sandbox: 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.

Примеры промптов

После подключения вы можете попросить своего ИИ-агента:

"Отправь STK Push на сумму 500 KES на номер +254712345678 для заказа #1234"

"Проверь, был ли получен платеж QKL8ABC123"

"Отправь SMS этим 5 фермерам с сегодняшней ценой на кукурузу: [список]"

"Пополни баланс на 50 KES для наших полевых агентов: [список номеров]"

Реальные сценарии

Выплата полевым агентам

"Отправь STK Push на 300 KES каждому из этих 12 полевых агентов для сегодняшнего сбора данных: [список]"

Агент последовательно запускает 12 STK-запросов, отслеживает каждый checkout_request_id и опрашивает систему для подтверждения — без написания кода с вашей стороны.

Оповещение фермеров + пополнение баланса

"Отправь SMS этим 200 фермерам в Гариссе, что уровень реки поднимается. Затем пополни баланс каждого на 20 KES, чтобы они могли позвонить и сообщить отчеты."

Один промпт → 200 SMS-сообщений и 200 пополнений баланса в сетях Safaricom, Airtel и Telkom.

Сверка платежей

"Проверь, был ли платеж по квитанции OKL8M3B2HF успешным и на какую сумму"

Полезно для агентов поддержки, использующих Claude для проверки транзакций M-Pesa в режиме реального времени.

Аннотации инструментов

Все инструменты объявляют аннотации инструментов MCP, чтобы клиенты могли соответствующим образом ограничивать вызовы:

Claude Desktop и другие MCP-клиенты будут запрашивать подтверждение перед запуском операций оплаты, отправки SMS или пополнения баланса.

Обнаружение сервера

Возможности анонсируются через .well-known/mcp.json — новый стандарт MCP Server Cards. Реестры и браузеры могут индексировать инструменты этого сервера без подключения к нему.

# 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 отвечает за уровень инструментов ИИ-агента — позволяя ИИ-помощникам программировать запуск и проверку платежей M-Pesa.

Они дополняют друг друга:

• Mojaloop: рельсы совместимости между финансовыми провайдерами

• mpesa-mcp: интерфейсный слой MCP, который соединяет ИИ-агентов с этими рельсами

См. вклад в документацию Mojaloop для получения дополнительной информации об этом шаблоне.

MCP против A2A — два разных протокола

mpesa-mcp реализует MCP (Model Context Protocol) — то, как ИИ-агент взаимодействует с инструментами.

Существует дополнительный протокол, A2A (Agent-to-Agent), который управляет тем, как агенты общаются друг с другом. Они решают разные задачи и работают вместе:

• MCP: Ваш ИИ-агент → 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 для получения уведомлений о релизах.