M-Pesa Daraja

一个 MCP 服务，将 Safaricom 的 Daraja API 作为工具提供出来，让 Agent（Claude Code、Codex、Cursor、Gemini CLI 及任何 MCP 客户端）可以收款、检查付款是否成功，并通过聊天操作 M-Pesa。它默认在沙盒中运行；只有在你启用后才会进行真实操作。

它与同一套件中的 Agent Skills 配合使用：这些技能教 Agent 如何集成 M-Pesa，而此服务则让它能够调用 Daraja。你也可以单独使用其中任意一项。

适用对象

• 开发者：构建支付集成；让 Agent 在沙盒中运行请求，并读取真实响应。
• 学习者：了解 Daraja API 的工作方式；向安全的测试环境发送真实请求，查看返回结果。
• 企业和团队：希望 AI Agent 处理支付，包括收款、检查付款是否成功以及对账。

安装

让你的 Agent 来安装。 将以下内容粘贴到 Claude Code、Codex、Cursor、Gemini CLI 或任何编码 Agent 中：

Add the M-Pesa Daraja MCP server to yourself, named "mpesa", with the command: uvx mpesa-daraja-mcp
It needs no keys in your config. If uv is missing, tell me how to install it first.
Don't ask me for my Daraja keys. Tell me to run `uvx mpesa-daraja-mcp setup` in my own terminal,
which saves them privately, then to restart you.
After I restart you, call mpesa_check_credentials and tell me if everything works.

或者自行安装。 你需要 uv。向导会要求你提供 Daraja 密钥（输入密钥时会隐藏），通过 Safaricom 实时验证密钥，将密钥保存到只有你能读取的文件中，并向 Claude Code、Codex、Gemini CLI 或 Cursor 注册此服务：

uvx mpesa-daraja-mcp setup

然后重启 Agent 并询问："检查我的 M-Pesa 凭据，然后向 0712345678 发送 KES 1 的 STK 推送，并在付款后告诉我。" 包含技能和更多示例的完整 Agent Kit 请参阅主 README。

工具

工具	Daraja API	是否转移资金
mpesa_explain_code	— 离线查询错误码／结果码
mpesa_normalize_phone	— 离线将 07… 转换为 2547…
mpesa_generate_stk_password	— 离线生成 Password + EAT Timestamp
mpesa_parse_callback	— 离线解析任意回调负载
mpesa_setup_status	— 离线查看每个工具集的配置和缺失项（不显示值）
mpesa_check_credentials	OAuth 令牌（绝不返回）
mpesa_get_result	按幂等键或任何 Daraja ID 查询最终状态（使用捕获的回调；STK 会回退到 STK Query）
mpesa_stk_push_and_wait	M-Pesa Express：发起推送，然后等待回调／轮询查询；返回 SUCCESS、FAILED 或 UNKNOWN	✅
mpesa_stk_push / mpesa_stk_query	M-Pesa Express，发起后不等待／状态	✅ /
mpesa_c2b_register_urls / mpesa_c2b_simulate	C2B v2（simulate 仅限沙盒）
mpesa_pull_transactions	Pull Transactions 查询
mpesa_b2c_payment	B2C v3、B2Pochi	✅
mpesa_b2b_payment	BusinessPayBill、BusinessBuyGoods、BusinessPayToBulk（B2C 充值）、PayTaxToKRA	✅
mpesa_b2b_express_checkout	B2B USSD 推送	✅
mpesa_transaction_status / mpesa_account_balance	状态／余额（异步结果）
mpesa_reverse_transaction	撤销交易	✅
mpesa_generate_dynamic_qr	动态 QR，保存为 PNG 文件（返回路径，不返回图片）
mpesa_ratiba_create_standing_order	M-Pesa Ratiba	✅
mpesa_bill_manager_optin / mpesa_bill_manager_send_invoice / mpesa_bill_manager_cancel_invoice	Bill Manager

工具注释会将转移资金的工具标记为 destructiveHint，因此 MCP 客户端会请求批准。

安全性

• 默认使用 sandbox。
• 在生产环境中，除非设置 DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=true，否则涉及资金转移的工具会拒绝运行。
• 回调 URL 必须使用 HTTPS；包含 mpesa/safaricom 的 C2B URL 会被提前拒绝。
• 工具输出绝不会返回令牌和密钥。
• ResponseCode "0" 的响应会标记为 _note: ACCEPTED for processing only，避免 Agent 将其报告为已完成的付款。
• 幂等的资金工具。 每个请求都会按幂等键存储。重复使用该键会返回已存储的请求（duplicate: true），而不会再次付款。
  • 只有明确标记为 FAILED 的请求才会重新发送。
  • 在结果明确之前，ACCEPTED 或 UNKNOWN 请求（队列超时、网络错误）绝不会重新发送。
  • B2C、B2B 和 B2B Express 必须提供明确的 idempotency_key，例如 refund-order-1042。Reversal、tax 和 Ratiba 会分别根据交易 ID、PRN 以及手机号 + 姓名生成幂等键。STK 的幂等键为可选项。

配置

变量	必需	说明
DARAJA_ENV		sandbox（默认）或 production
DARAJA_CONSUMER_KEY、DARAJA_CONSUMER_SECRET	✅	来自你的 Daraja 应用
DARAJA_SHORTCODE	大多数工具	Paybill / 商店编号（sandbox 中为 174379）
DARAJA_PASSKEY	STK	Lipa na M-Pesa passkey
DARAJA_INITIATOR_NAME	B2C/B2B/status/balance/reversal	API 操作员用户名
DARAJA_SECURITY_CREDENTIAL	同上	预加密的凭据，或者设置接下来的两个变量
DARAJA_INITIATOR_PASSWORD + DARAJA_CERT_PATH		服务器会在启动时使用证书加密密码
DARAJA_CALLBACK_BASE_URL		例如 https://abc.ngrok-free.app；工具会追加 /mpesa/stk/callback、/mpesa/b2c/result 等路径
DARAJA_ALLOW_LIVE_MONEY_MOVEMENT		设为 true 以允许生产环境中的扣款/付款
DARAJA_CALLBACK_LISTEN		例如 127.0.0.1:8787：启动内置回调接收器
DARAJA_CALLBACK_TOKEN	使用接收器时	16 个以上的随机字符。回调 URL 会变为 <base>/cb/<token>/…
DARAJA_STATE_DB		用于存储请求和结果的 SQLite 文件（默认值：~/.mpesa-mcp/state.db）
DARAJA_TOOLSETS		以逗号分隔的 stk,c2b,payouts,ops,qr,ratiba,billmanager 列表（core 始终启用）。默认值：全部
DARAJA_OUTPUT_DIR		保存 QR PNG 的位置（默认值：~/.mpesa-mcp/qr）

命令和配置文件

uvx mpesa-daraja-mcp setup     # guided: keys (hidden input), live check, save, register with your agents
uvx mpesa-daraja-mcp status    # what's configured (masked) + a live key check
uvx mpesa-daraja-mcp           # the MCP server itself, on stdio: what your agent runs

服务器无需在 Agent 的配置中设置任何标志或环境变量。设置按以下顺序读取，优先级从高到低：

1. 环境变量，例如客户端的 env 区块中的变量。
2. 项目 .env 文件，位于 Agent 启动服务器的文件夹中，或由 DARAJA_DOTENV 指定的文件。只读取 DARAJA_* 行。
3. 用户配置文件，由 setup 写入：~/.config/mpesa-daraja-mcp/config.env（Windows：%APPDATA%\mpesa-daraja-mcp\config.env；使用 DARAJA_CONFIG_DIR 更改文件夹）。该文件仅你可读取。

即使尚未配置，服务器也会启动。此时，工具会说明缺少哪些配置，mpesa_setup_status 会列出每个工具集尚缺的配置，但不会透露任何配置值。

手动注册：claude mcp add --scope user mpesa -- uvx mpesa-daraja-mcp。其他 Agent 的配置方法见 docs/clients.md。旧版 mpesa-mcp 命令仍然可用。

结果和回调

每个资金相关或异步工具都返回同一种结构：

{"status": "ACCEPTED | SUCCESS | FAILED | UNKNOWN", "message": "...", "idempotency_key": "...",
 "duplicate": false, "ids": {"checkout_request_id": "..."}, "receipt": "...", "result_code": "...",
 "explanation": "...", "raw": {}}

若要让 Agent 获取最终结果，请启用内置接收器：

export DARAJA_CALLBACK_LISTEN=127.0.0.1:8787
export DARAJA_CALLBACK_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(24))")
ngrok http 8787                        # sandbox; use a reverse proxy with TLS in production
export DARAJA_CALLBACK_BASE_URL=https://<tunnel-host>

回调会存储在 DARAJA_STATE_DB 中：

• mpesa_get_result(id) 会读取回调。
• mpesa_stk_push_and_wait 会在一次调用中返回最终结果。
• 队列超时对应的回调会记录为 UNKNOWN。
• C2B 验证请求始终会被接受。如果需要拒绝付款，请使用自己的接收器。

未启用接收器时，mpesa_stk_push_and_wait 仍会通过 STK Query 正常工作。对于其他 API，请将收到的载荷粘贴到 mpesa_parse_callback 中。

仅加载所需的工具

服务器提供的每个工具都会占用 Agent 的上下文空间，即使从未调用也一样。将 DARAJA_TOOLSETS 设置为你使用的工具组，Agent 就只会看到这些工具。基本工具（core）始终启用；不设置此项则会加载所有工具。

设置	可用内容	适用场景
未设置（默认）	全部 24 个工具	探索所有功能
stk	基本工具及 3 个 STK Push 工具	只接受 STK 付款的商店
stk,payouts	上述工具，以及 B2C、B2B 和 B2B Express	提供收款和付款的平台
stk,c2b,ops	STK、C2B，以及交易状态、余额和撤销工具	对账和支持

工具组包括 stk、c2b、payouts、ops、qr、ratiba 和 billmanager。

开发

pip install -e ".[dev]"
pytest

测试使用 respx 模拟 Daraja，不会访问网络。

许可证

MIT © 2026 Mr-Macharia。这是一个独立的开源项目，与 Safaricom PLC 无关，也未获得其认可。M-Pesa 和 Daraja 是 Safaricom PLC 的商标。