AI导哈

M-Pesa支付集成服务器

一个基于Go语言实现的M-Pesa支付集成服务器，用于AI代理的支付处理，支持STK Push、二维码生成和支付回调处理。

  • by skanenje
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 skanenje/mpesa-mcp

使用说明

M-Pesa MCP服务器（Go实现）

内置于Go中的模型上下文协议（MCP）服务器，用于将M-Pesa支付与AI代理集成。

⚠️ 重要提示：这可以处理真实货币交易！
在生产中使用之前，请阅读 了解付款流程 和审查 安全最佳实践始终首先在沙盒模式下进行彻底测试。

🎯 这有什么作用

此MCP服务器允许AI代理（如使用Google ADK、LangChain、Claude Desktop构建的代理）：

  • 启动M-Pesa STK推送支付（提示客户通过手机支付）
  • 生成M-Pesa二维码进行支付
  • 检查身份验证令牌状态
  • 新 处理M-Pesa支付回调（webhooks）

这个项目的新手？ → 从 快速入门指南 （5分钟）

想要整合吗？ → 结账 集成示例

💰 了解付款流程

在使用此服务器之前，了解以下内容至关重要：

CUSTOMER (PartyA)  →  Pays Money  →  YOUR BUSINESS (PartyB)
   254712345678                         Your Shortcode/Till

资金流总是：

  • 从：客户的M-Pesa账户（您指定的电话号码）
  • 到：您的企业帐户（在中配置 .env 作为 BUSINESS_SHORTCODE)

所有付款都会转到您的企业账户，而不是代理或服务器运营商。

📖 阅读完整指南: 支付流程和用例

📚 文档

入门指南

整合

部署和运营

额外资源

🚀 快速开始

先决条件

  1. 转到1.22+ 安装
  2. Safaricom Daraja API证书 -让他们在https://daraja.safaricom.co.ke/

安装

# Clone the repository
git clone https://github.com/skanenje/mpesa-mcp.git
cd mpesa-mcp

# Configure environment
cp .env.example .env
# Edit .env with your Daraja credentials
# ⚠️ IMPORTANT: Use RAW passkey, not base64 encoded!
# See docs/PASSKEY_GUIDE.md for details

# Build and run
go build -o mpesa-mcp cmd/server/main.go
./mpesa-mcp

服务器将于启动 http://localhost:8080

完整的设置说明: 安装指南
密钥配置: 密钥指南

🛠️ 可用工具

1. stk_push

发起STK Push付款请求（向客户的手机发送付款提示）。

{
  "name": "stk_push",
  "arguments": {
    "amount": 1000,
    "phone_number": "254712345678"
  }
}

2. generate_qr_code

生成M-Pesa二维码，客户可以扫描该二维码进行支付。

{
  "name": "generate_qr_code",
  "arguments": {
    "merchant_name": "My Store",
    "ref_no": "ORDER123",
    "amount": 500,
    "trx_code": "BG",
    "cp_identifier": "123456"
  }
}

3. get_token_status

检查OAuth令牌状态（有助于调试身份验证问题）。

API完整文档: api参考

🔌 集成示例

Python客户端

from mpesa_mcp_client import MPesaMCPClient

client = MPesaMCPClient()
client.connect()

result = client.call_tool("stk_push", {
    "amount": 100,
    "phone_number": "254712345678"
})

谷歌ADK代理

from google.adk import Agent

agent = Agent(
    name="payment-assistant",
    model="gemini-2.0-flash-exp",
    tools=[mpesa.stk_push],
    instruction="You help process M-Pesa payments."
)

response = agent.run("Charge customer 254712345678 KES 1000")

更多示例: 集成指南 | 示例目录

🏗️ 建筑

┌─────────────────────────────────────────┐
│     AI Agent Layer                      │
│  (Google ADK, LangChain, Claude, etc.)  │
└────────────┬────────────────────────────┘
             │ JSON-RPC over SSE/HTTP
┌────────────▼────────────────────────────┐
│     M-Pesa MCP Server (Go)              │
│  - HTTP Server (Port 8080)              │
│  - MCP Tool Handlers                    │
│  - M-Pesa Client                        │
└────────────┬────────────────────────────┘
             │ HTTPS + Bearer Token
┌────────────▼────────────────────────────┐
│     Safaricom Daraja API                │
└────────────┬────────────────────────────┘
             │ Push Notification
┌────────────▼────────────────────────────┐
│     Customer's Phone                    │
└─────────────────────────────────────────┘

详细架构: 建筑.md

📝 测试

# Start the server
./mpesa-mcp

# Test health endpoint
curl http://localhost:8080/health

# Test STK Push
curl -X POST "http://localhost:8080/message?session=SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "stk_push",
      "arguments": {
        "phone_number": "254712345678",
        "amount": 100
      }
    }
  }'

更多测试示例: 故障排除指南

🚀 部署

码头工人

docker build -t mpesa-mcp .
docker run -p 8080:8080 \
  -e MPESA_CONSUMER_KEY=your_key \
  -e MPESA_CONSUMER_SECRET=your_secret \
  mpesa-mcp

云平台

支持部署到：

  • 谷歌云运行
  • AWS ECS/Fargate
  • Heroku
  • Kubernetes

完整部署指南: 部署指南

🔐 安全

在投入生产之前：

  • []使用生产Daraja凭据（不是沙盒）
  • []使用有效的SSL证书设置HTTPS
  • []实现回调端点验证
  • []启用速率限制
  • []配置日志记录和监控
  • []与Safaricom完成KYC验证

完整的安全检查表: 安全最佳实践

🤝 贡献

我们欢迎捐款！看 贡献.md 作为指导方针。

我们需要帮助的领域：

  • 增加更多M-Pesa API业务（B2C、B2B等）
  • 编写测试（单元和集成）
  • 为更多框架创建集成示例
  • 改进文件

📄 许可证

麻省理工学院许可证-您可以在项目中自由使用！

📚 额外资源

⚠️ 免责声明

这是出于教育目的。始终：

  • 生产前在沙箱中进行彻底测试
  • 遵循Safaricom的服务条款
  • 实施适当的错误处理
  • 保护您的凭据
  • 验证服务器端的所有付款

问题？ 检查 故障排除指南 或者打开一个问题。

相关 MCP