mpesa-mcp

mpesa-mcp

面向东非金融科技 API 的 MCP 服务——M-Pesa（Safaricom Daraja）和 Africa's Talking

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

模型

此服务不推荐、认证或评测任何模型，get_model_hint() 仅为兼容性而保留（返回中立建议）。请使用能可靠遵循工具架构的模型，先在沙盒中演练，并确保每次涉及资金转移或消息发送的调用都由人工批准：在实时模式下，这些工具需要 confirm_send=true，且有调用上限（MPESA_MAX_AMOUNT_KES，默认 KES 100,000；MPESA_MAX_SMS_RECIPIENTS，默认 50）。

为什么要开发这个项目

M-Pesa 在非洲每天处理的交易量超过 PayPal。Africa's Talking 通过 SMS 和 USSD 覆盖 20 多个国家的基本款手机用户。两者都没有 MCP 服务。

这意味着，如今构建的每个 AI Agent——Claude、GPT、Gemini 或任何兼容 MCP 的运行时——都无法在没有自定义集成的情况下发起 M-Pesa 付款或发送斯瓦希里语短信。

mpesa-mcp 只需执行一次 pip install 即可弥补这一缺口。

工具

工具	描述
mpesa_stk_push	在客户的 M-Pesa 手机上触发 STK Push 付款提示
mpesa_stk_query	查询 STK Push 请求的状态
mpesa_transaction_status	按收据编号查询任意 M-Pesa 交易
sms_send	向非洲网络中的 1–1,000 名收件人发送短信
airtime_send	为任意用户充值话费（KES、NGN、GHS、UGX 等）

覆盖范围

• **M-Pesa：**肯尼亚（Safaricom Daraja v3）——STK Push、C2B、交易状态
• **SMS/话费充值：**通过 Africa's Talking 覆盖肯尼亚、尼日利亚、加纳、坦桑尼亚、乌干达、卢旺达、南非及其他 15 个以上国家

Glama（托管 MCP）

mpesa-mcp 可作为托管 MCP 服务通过 Glama 使用：

安全性：本项目如何对应 NSA 的 MCP 指南（自行评估，未经认证）

mpesa-mcp 已根据 **NSA CSI U/OO/6030316-26（2026 年 5 月）**进行了审查。该文件是 NSA 人工智能安全中心关于模型上下文协议安全性的网络安全信息表。该文件属于指导意见，而非可认证标准，因此下表是本项目的自行评估，不代表审计或认证。

控制领域	此服务的做法
参数验证	肯尼亚电话号码会经过规范化和验证；金额必须为正数，且在配置的限额范围内
审计日志	每次工具调用记录一条结构化日志；电话号码以截断的 SHA-256 哈希形式记录，其他标识符按原样记录；每次转出资金调用结束时，都会记录一条终端日志
支出限额	每笔付款上限、每个会话的预算、可选的收款人允许列表，以及实时模式下必须确认（见下文“有界授权”）
令牌生命周期	Daraja OAuth 令牌会连同到期时间一起缓存，并自动刷新
错误处理	Daraja API 错误会以结构化结果返回；意外异常只按类型记录日志后重新抛出，MCP 框架会将其报告给客户端
HTTPS	所有 Daraja API 调用均使用 HTTPS
机密信息	实时凭据来自环境变量；本 README 中的 Safaricom 沙盒测试短代码和密钥是公开示例，并非机密信息

关于如何报告漏洞，请参阅 SECURITY.md。

参考资料： NSA CSI_MCP_SECURITY.pdf（2026 年 5 月，非机密）

安装

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

沙盒凭据

新建 Daraja 账户，或要在新设备上进行设置？请按照沙盒设置指南操作：其中记录了经过验证的步骤（创建应用时只勾选 Lipa Na M-Pesa Sandbox，使用已发布的测试短代码和密钥，并将 MPESA_CALLBACK_URL 指向一个可供你查看的公网 HTTPS 地址），以及正常运行时的结果。Consumer 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 Agent 提出以下请求：

“向 +254712345678 发送 KES 500 的 STK Push，订单号为 #1234”

“检查是否已收到付款 QKL8ABC123”

“向这 50 位农民发送短信，告知他们今天的玉米价格：[列表]”

“为我们的外勤 Agent 充值 KES 50 话费：[号码列表]”

实际场景

外勤 Agent 付款派发

“向以下 12 位外勤 Agent 分别发送 KES 300 的 STK Push，用于今天的数据收集：[列表]”

Agent 会依次触发 12 次 STK Push，跟踪每个 checkout_request_id，并轮询确认结果——无需你编写任何代码。

农民预警和话费充值

“向这 200 位 Garissa 农民发送短信，告知他们河流水位正在上涨。然后为每人充值 KES 20 话费，让他们可以打电话报告情况。”

一条提示词 → 通过 Safaricom、Airtel 和 Telkom 发送 200 条短信并充值 200 笔话费。

付款对账

“检查收据 OKL8M3B2HF 对应的付款是否成功，以及金额是多少”

适用于使用 Claude 实时核实 M-Pesa 交易的客服人员。

工具注解

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

工具	readOnly	destructive	idempotent
mpesa_stk_push	❌	✅	❌
mpesa_stk_query	✅	❌	✅
mpesa_transaction_status	✅	❌	✅
sms_send	❌	✅	❌
airtime_send	❌	✅	❌

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

服务发现

此服务通过 .well-known/mcp.json 宣告其功能——这是新兴的 MCP 服务卡标准。注册表和浏览器无需连接此服务即可索引其工具。

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

测试与准确性

这些测试用于检查此服务的行为。本 README 不对任何模型使用此服务时的准确性作出声明。

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 推送、SMS、话费充值）在进行任何 API 调用前都会经过明确验证。

生态系统背景——Mojaloop + MCP

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

mpesa-mcp 负责AI Agent 工具层——让 AI 编码助手能够以编程方式发起和查询 M-Pesa 支付。

二者相辅相成：

• Mojaloop：金融服务提供商之间的互操作轨道
• mpesa-mcp：将 AI Agent 连接到这些轨道的 MCP 接口层

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

MCP 与 A2A——两种不同的协议

mpesa-mcp 实现了 MCP（Model Context Protocol，模型上下文协议）——用于 AI Agent 与工具通信。

另有一种互补协议 A2A（Agent-to-Agent，Agent 间协议），负责 Agent 之间的通信。二者解决不同的问题，可协同工作：

• MCP：你的 AI Agent → mpesa-mcp → Daraja API / Africa's Talking
• A2A：编排 Agent ↔ 支付子 Agent ↔ 通知子 Agent

大多数集成只需使用 MCP。当你构建由支付工作流与其他专用 Agent 协同工作的多 Agent 系统时，A2A 才会派上用场。

---

开发

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

安全

请勿提交 API 密钥。请使用环境变量或机密管理器。
漏洞请报告至：[email protected]

研究背景

斯瓦希里语与翻译（arXiv:2509.04516，2025）：在一项小规模新闻分类实验中，斯瓦希里语原生 BERT 模型的错误率为 0.36%，而应用于机器翻译后斯瓦希里语文本的英语模型错误率为 1.47%；因此，在该任务中，原生模型优于“先翻译再分类”。此服务的工具描述编写时兼顾斯瓦希里语和英语阅读；目前尚未测量这一做法的效果。

MCP 安全研究（arXiv:2603.18063，arXiv:2603.21642，2026）：通过工具描述进行提示词注入是 MCP 的主要攻击向量。mpesa-mcp 通过静态、带版本控制的工具描述和严格的输入验证来降低风险。

相关基础设施：

• wapimaji-mcp — 肯尼亚抗旱响应 MCP（模拟数据）
• civic-agent-kit — 肯尼亚公民数据 MCP
• swahili-health-mcp — 肯尼亚 DHS 2022 县级健康指标 MCP
• kenya-legal-rag — 肯尼亚法律语料库 MCP
• 完整项目集：gabrielmahia.github.io

许可证

MIT — © 2026 Gabriel Mahia

获取最新动态

获取新版本发布和东非 API 发展的通知： 订阅更新 →

也可以在 GitHub 上关注此仓库，以接收版本发布通知。

相关软件包

软件包	安装	描述
wapimaji-mcp	pip install wapimaji-mcp	模拟干旱阶段和 SMS 警报的 MCP 服务（目前尚无真实 NDMA 数据）
civic-agent-kit	pip install civic-agent-kit	东非公民 AI SDK

相关软件包

均采用 MIT 许可证 · 均属于东非公民 AI 技术栈

软件包	安装	描述
wapimaji-mcp	pip install wapimaji-mcp	模拟干旱阶段和 SMS 警报的 MCP 服务（目前尚无真实 NDMA 数据）
kenya-health-mcp	pip install kenya-health-mcp	肯尼亚健康数据 MCP — SHA/SHIF、医疗机构、孕产妇、权益
civic-agent-kit	pip install civic-agent-kit	东非公民 AI SDK

完整项目集：gabrielmahia.github.io

东非协调技术栈的一部分

此 MCP 服务是肯尼亚协调基础设施的一部分。 将其连接到 africa-coord-bus — 这是一个协调事件总线，可自动在不同领域之间路由信号。

pip install africa-coord-bus

所有服务：pypi.org/user/gmahia 在线演示：coord-cascade-demo

知识产权与协作

采用 MIT 许可证。仅通过 GitHub Issues 接收反馈 — 不接受拉取请求。演示数据标注为 DEMO，不适用于运营决策。完整政策：docs/architecture/IP_POLICY.md。安全问题报告：请参阅 SECURITY.md。

东非协调技术栈的一部分

• 安装并运行： pip install reli-cli && reli list — 官方 MCP Registry 中 io.github.gabrielmahia 名下的 MCP 服务
• 评估任意模型在斯瓦希里语 Agent 任务上的表现： kipimo · 数据集 · 排行榜
• 跨服务协调： africa-coord-bus — 离线优先事件总线，内置肯尼亚路由表
• 数据集： huggingface.co/gmahia · 文档中心： nairobi-stack

本项目在设计上与模型无关：封闭 API、开放权重模型和小型蒸馏模型均受到一视同仁。

资金转出工具的安全限制（0.3.0，实况模式下为破坏性变更）

语言模型可能被诱导向任何人支付任意金额：针对支付工具的提示词注入，是一种有记录在案的 Agent 支付协议（AP2、x402）攻击。因此，在实况模式（MPESA_SANDBOX=false）下，八种资金转出工具（mpesa_b2c、mpesa_business_paybill、mpesa_business_buygoods、mpesa_business_pochi、mpesa_reversal、mpesa_tax_remittance、mpesa_b2b_express_checkout、airtime_send）受到以下限制：

• **确认：**除非调用时设置 confirm_send=true，否则这些工具会拒绝请求。Agent 必须向用户展示收款人和金额，并且只有在获得明确批准后才能设置该参数。
• **上限：**超过 MPESA_MAX_AMOUNT_KES（默认值为 20,000；0 = 不设上限）的金额将被拒绝。
• 会话预算：单个服务进程最多可授权转出总额 MPESA_SESSION_BUDGET_KES（默认值为 50,000；0 = 不设预算）。上限约束单笔付款；预算约束总额，因此 Agent 无法无限次重复支付达到上限的金额。付款获批时即计入预算；即使调用随后失败，也不会退还预算（超时的调用仍可能已经转出资金）。只有重启服务后预算才会重置。只有运营方可以更改预算，模型无法更改。如果你确实需要在单个会话中转出超过 300,000 KES，请调高预算。
• 由用户确认，而非模型确认（0.5.0）：在实况模式下，对于八种资金转出工具，服务会通过你的 MCP 客户端，请你在执行任何操作前批准确切的付款信息（完整收款人、金额、参考信息）；无论使用哪个协议版本，都会通过 MCP elicitation 实现。模型无法代替你作答：它可以设置 confirm_send=true，但你仍然可以拒绝。批准仅适用于该次确切调用（金额或收款人不同就需要重新批准），只能使用一次，并会在五分钟后过期。对于服务本来就会拒绝的付款（超过上限、超过预算、不在允许名单内），不会向你发起确认。MPESA_CONFIRM_MODE：auto（默认：客户端可以响应时发起确认；否则回退到 confirm_send 参数）、elicit（严格模式：客户端无法显示提示时拒绝请求）或 param（旧行为）。沙盒模式不会发起确认。目前并非所有客户端都支持 elicitation；如果你的客户端不支持，请使用 elicit 模式以便在无法确认时拒绝，而不是回退，并保持客户端自身的逐次调用审批功能开启。
• **允许的收款人：**设置 MPESA_ALLOWED_RECIPIENTS（以逗号分隔的电话号码、paybill 和 till），资金转出工具便只会向这些收款人付款；其他收款人均会被拒绝。电话号码可以是任何肯尼亚格式。不设置此项表示不作限制；对于生产环境，建议配置允许名单：限定可付款对象，与使用限定商户的支付令牌或预留款项供指定商户使用，是同一思路。冲正和税款汇缴没有可自由指定的收款人，因此此名单不适用于它们。
• 会话报告：mpesa_session_report 工具为只读，会返回限制、已支出金额、剩余金额，以及服务自身记录中最近十次授权或拒绝的记录（收款人信息已掩码）。付款前可用它检查预算，并核实服务实际授权的内容，而不是依赖模型对其操作的描述。

也要限制工具外部的损失

这些防护措施在工具内部运行，而工具是 Agent 可以控制的层。还有两项检查在工具之外，你应当同时使用，并将限额设得尽可能低：

1. confirm_send 由模型本身提供，因此单靠它并不是独立检查。自 0.5.0 起，服务端会通过你的客户端直接向你询问（见上文）；如果你的客户端无法显示该提示，请为八个资金转出工具保留 MCP 客户端自身的逐次调用审批，且绝不要将其设为“始终允许”。
2. 限制支付渠道中的损失。 使用专用的企业短代码或工作账户进行付款，该账户中只存放你能够承受损失的金额；并使用 M-PESA 组织账户提供的发起人限额或审批（经办人-复核人）控制措施。本服务端无法查看这些设置，因此请查阅 Safaricom 的最新文档。

印度的 Agentic 支付试点（预先注资、限定商户的预留款，以及由网络强制执行的委托限额）和 Alipay 的 Agent 支付（由用户设置阈值，阈值以下 Agent 可以付款，超过阈值则由人员确认；提供审核并撤销 Agent 授权的方式，以及损失保障）都独立采用了这种分层设计。

3. 从小额开始。 此处的默认值（每笔付款 20,000 KES，每个会话 50,000 KES；在 0.5.0 中从 100,000 和 300,000 下调）是上限，不是建议额度。巴西银行允许客户通过 WhatsApp 上的 AI 助手进行语音或文字支付，单笔起始金额约为 R$200 至 R$800，每笔都要求确认，金额更大的付款则转到银行自己的应用中处理：这与此处的默认值处于同一数量级。将 MPESA_MAX_AMOUNT_KES 和 MPESA_SESSION_BUDGET_KES 设为实际所需的最低金额，只有在有理由时才提高。

• 选择退出： MPESA_REQUIRE_CONFIRMATION=false 会为你控制的全自动设置取消确认要求。只有在经过慎重考虑后才这样做。
• 沙盒不会受到任何限制。 经客户批准的流程（STK Push、Ratiba、Bill Manager）不变：客户仍需在自己的手机上批准。