mpesa-mcp

用于东非金融科技 API 的 MCP 服务器 — M-Pesa (Safaricom Daraja) 和 Africa's Talking

让你的 AI 智能体能够触发 M-Pesa 支付、检查交易状态、发送短信，并为 20 多个非洲电信网络充值话费。

为什么存在这个项目

M-Pesa 在非洲每天处理的交易量超过了 PayPal。Africa's Talking 通过短信和 USSD 在 20 多个国家/地区覆盖了使用基础手机的用户。但两者都没有 MCP 服务器。

这意味着当今构建的每一个 AI 智能体（Claude、GPT、Gemini 或任何兼容 MCP 的运行时）如果不进行自定义集成工作，都无法触发 M-Pesa 支付或发送斯瓦希里语短信。

mpesa-mcp 通过一次 pip install 填补了这一空白。

工具

覆盖范围

• M-Pesa: 肯尼亚 (Safaricom Daraja v3) — STK 推送、C2B、交易状态

• 短信/话费: 肯尼亚、尼日利亚、加纳、坦桑尼亚、乌干达、卢旺达、南非以及通过 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 之前在你的 shell 中设置环境变量。

示例提示词

连接后，你可以询问你的 AI 智能体：

"Send KES 500 STK Push to +254712345678 for order #1234"

"Check if the payment QKL8ABC123 has been received"

"Send an SMS to these 50 farmers with today's maize price: [list]"

"Top up KES 50 airtime for our field agents: [list of numbers]"

实际应用场景

外勤人员支付调度

"Send KES 300 STK Push to each of these 12 field agents for today's data collection: [list]"

智能体触发 12 次连续的 STK 推送，跟踪每个 checkout_request_id，并轮询确认结果 — 无需你编写任何代码。

农民提醒 + 话费充值

"SMS these 200 Garissa farmers that the river is rising. Then top up KES 20 airtime each so they can call in reports."

一个提示词 → 200 条短信和 200 次话费充值，覆盖 Safaricom、Airtel 和 Telkom。

支付对账

"Check whether receipt OKL8M3B2HF was a successful payment and how much it was for"

适用于使用 Claude 实时验证 M-Pesa 交易的支持人员。

工具注解

所有工具都声明了 MCP 工具注解，以便客户端可以适当地控制调用：

Claude Desktop 和其他 MCP 客户端会在触发支付、短信或话费操作前请求确认。

服务器发现

功能通过 .well-known/mcp.json 进行通告 — 这是新兴的 MCP 服务器卡片标准。注册表和浏览器可以在不连接的情况下索引此服务器的工具。

# 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 推送、短信、话费）在进行任何 API 调用之前都有明确的验证。

生态系统背景 — Mojaloop + MCP

Mojaloop（由盖茨基金会资助）处理支付互操作性 — 连接东非及其他地区的银行、移动货币钱包和商户。

mpesa-mcp 处理* AI 智能体工具层* — 使 AI 编码助手能够以编程方式触发和查询 M-Pesa 支付。

它们是互补的：

• Mojaloop：金融提供商之间的互操作性轨道

• mpesa-mcp：将 AI 智能体连接到这些轨道的 MCP 接口层

有关此模式的更多信息，请参阅 Mojaloop 文档贡献。

MCP 与 A2A — 两种不同的协议

mpesa-mcp 实现了 MCP（模型上下文协议）— AI 智能体如何与工具对话。

还有一个互补协议 A2A（智能体对智能体），它处理智能体如何相互对话。它们解决不同的问题并协同工作：

• 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 上关注此仓库以获取发布通知。