Daraja MCP

🚀 萨法利通信达拉拉贾MCP服务器

这是一个模型上下文协议（MCP）服务器，它将萨法利通信（Safaricom）的M-PESA达拉拉贾（Daraja）API与Claude集成，实现自然语言支付处理和实时交易通知功能。

🚀 快速开始

前提条件

• 系统中安装 Python 3.10+。
• 拥有 达拉拉贾API账户，可在 developer.safaricom.co.ke 注册。
• （可选）安装 ngrok 用于测试回调，可从 ngrok.com 下载。
• （可选）安装 Claude桌面版 用于MCP集成。

安装步骤

1. 克隆仓库

# 克隆仓库
git clone https://github.com/mboya/daraja-mcp.git
cd daraja-mcp

# 若已克隆仓库，直接进入目录
cd daraja-mcp

2. 设置虚拟环境

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate

# Windows:
venv\Scripts\activate

激活后，终端提示符前应显示 (venv)。

3. 安装依赖

# 从requirements.txt安装所有必需的包
pip install -r requirements.txt

这将安装以下包：

• mcp - 模型上下文协议服务器
• requests - 用于API调用的HTTP库
• flask - 用于回调服务器的Web框架
• python-dotenv - 环境变量管理工具
• gunicorn - WSGI HTTP服务器（用于生产部署）

4. 配置环境变量

在项目根目录下创建 .env 文件，仓库中包含 .env.example 文件作为模板。 快速设置：

# 复制示例文件
cp .env.example .env

# 使用你喜欢的文本编辑器（如nano、vim、code等）编辑.env文件
nano .env

然后将占位符值替换为你实际的达拉拉贾API凭证（见下面的 获取达拉拉贾凭证 部分）。

运行服务器

快速启动

完成上述安装和配置步骤后，按以下步骤运行服务器：

1. 验证设置

# 确保你在项目目录中
cd daraja-mcp

# 激活虚拟环境
source venv/bin/activate  # macOS/Linux
# 或者
venv\Scripts\activate     # Windows

# 验证.env文件是否存在
ls -la .env  # macOS/Linux
# 或者
dir .env     # Windows

2. 运行服务器
   • 本地开发并使用Claude桌面版

# 激活虚拟环境（如果尚未激活）
source venv/bin/activate

# 运行服务器
python server.py

- **生产/云部署**

# 激活虚拟环境
source venv/bin/activate

# 使用Python运行（用于测试）
python server_http.py

# 或者使用gunicorn运行（用于生产）
gunicorn server_http:app --bind 0.0.0.0:3000 --workers 2

3. 验证服务器是否运行
   • 检查输出：应看到以下内容

🚀 达拉拉贾MCP服务器启动中...
📡 回调服务器正在0.0.0.0:3000上运行
🌐 公共回调URL: http://localhost:3000/mpesa/callback
🔧 环境: 沙盒

- **测试健康端点**：在新终端中运行

curl http://localhost:3000/health

预期响应：

{
  "status": "healthy",
  "callback_url": "http://localhost:3000/mpesa/callback",
  "unread_payments": 0
}

4. 设置ngrok（用于本地测试真实回调） 如果在本地开发期间需要接收真实的M-PESA回调：

# 在新终端中启动ngrok
ngrok http 3000

# 复制HTTPS URL（例如，https://abc123.ngrok.io）
# 更新.env文件：
PUBLIC_URL=https://abc123.ngrok.io

# 重启服务器
python server.py

5. 与Claude桌面版集成
   1. 打开Claude桌面版设置。
   2. 添加MCP服务器配置（见 与Claude桌面版集成 部分）。
   3. 重启Claude桌面版。
   4. 开始聊天并使用自然语言处理支付！

不同场景下的运行方式

场景1：本地开发（无需回调）

source venv/bin/activate
python server.py

• 用于在本地测试MCP工具。
• 回调功能将无法使用（本地主机无法从互联网访问）。
• 适合开发和调试。

场景2：本地开发（使用ngrok进行回调）

# 终端1：启动ngrok
ngrok http 3000

# 终端2：使用ngrok URL更新.env文件，然后启动服务器
source venv/bin/activate
python server.py

• 用于测试带有真实回调的完整支付流程。
• ngrok提供公共HTTPS URL。
• 萨法利通信可以访问你的回调端点。

场景3：生产部署（Railway/Heroku）

# 部署到Railway（从git push自动部署）
git push origin main

# 或者在本地使用生产设置运行
source venv/bin/activate
gunicorn server_http:app --bind 0.0.0.0:3000 --workers 2

• 生产环境使用 server_http.py。
• Railway自动提供HTTPS。
• 无需ngrok。

启动问题排查

• “无法分配请求的地址”：在macOS上绑定 0.0.0.0 时经常出现此问题。在本地开发时使用 127.0.0.1：

# 在.env文件中设置：
CALLBACK_HOST=127.0.0.1

如果 .env 文件中 CALLBACK_HOST 已经设置为 0.0.0.0，将其更改为 127.0.0.1 或删除该行以使用默认值。服务器仍然可以与ngrok一起工作（ngrok将转发到本地主机）。

• 端口已被使用：

# 检查哪个进程正在使用3000端口
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# 杀死该进程或更改.env文件中的CALLBACK_PORT

• 缺少依赖项：

# 重新安装依赖项
pip install -r requirements.txt

• 环境变量未加载：

# 验证.env文件是否存在且值正确
cat .env

# 测试加载
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.getenv('DARAJA_CONSUMER_KEY'))"

• 服务器启动但健康检查失败：

# 检查Flask回调服务器是否正在运行
curl http://localhost:3000/health

# 检查服务器日志中的错误
# 在运行server.py的终端中查找错误消息

✨ 主要特性

• STK推送支付：通过自然语言发起M-PESA支付请求。
• 实时回调：使用Flask服务器自动处理支付通知。
• 支付跟踪：存储和查询支付历史记录，并显示已读/未读状态。
• 自然语言界面：通过Claude对话与M-PESA进行交互。
• 沙盒测试：全面支持达拉拉贾沙盒环境。
• 自动化测试：拥有全面的测试套件进行验证。

📦 安装指南

环境变量

仓库中包含 .env.example 文件，其中包含所有必需的环境变量。设置环境的步骤如下：

1. 复制示例文件：

cp .env.example .env

2. 编辑 .env 文件，使用实际凭证：

# 使用nano
nano .env

# 或者使用你喜欢的编辑器
code .env  # VS Code
vim .env   # Vim

3. 替换占位符值 为你实际的达拉拉贾API凭证：

• DARAJA_CONSUMER_KEY - 你从达拉拉贾门户获取的消费者密钥。
• DARAJA_CONSUMER_SECRET - 你从达拉拉贾门户获取的消费者密钥。
• DARAJA_SHORTCODE - 你的业务短代码（沙盒环境为174379）。
• DARAJA_PASSKEY - 你从达拉拉贾门户获取的密码。
• PUBLIC_URL - 你的公共回调URL（本地测试使用ngrok URL）。

示例 .env 文件结构：

# 达拉拉贾API凭证
DARAJA_CONSUMER_KEY=your_consumer_key_here
DARAJA_CONSUMER_SECRET=your_consumer_secret_here
DARAJA_SHORTCODE=174379
DARAJA_PASSKEY=your_passkey_here

# 环境（沙盒或生产）
DARAJA_ENV=sandbox

# 回调服务器配置
CALLBACK_PORT=3000
CALLBACK_HOST=127.0.0.1
PUBLIC_URL=http://localhost:3000

重要提示：

• 本地开发使用 CALLBACK_HOST=127.0.0.1 以避免在macOS上出现 “无法分配请求的地址” 问题。
• 切勿将 .env 文件提交到版本控制！（它已经在 .gitignore 中）
• .env.example 文件可以安全提交，作为模板使用。
• 对于生产部署，在托管平台（如Railway、Heroku等）中设置环境变量。

项目文件

仓库中已经包含所有必要的文件：

• server.py - 用于本地Claude桌面版集成的MCP服务器（stdio）。
• server_http.py - 用于云/生产部署的MCP服务器（HTTP）。
• test_daraja.py - 全面的测试套件。
• quick_test.py - 快速验证脚本。
• requirements.txt - Python依赖项（已配置）。
• .gitignore - Git忽略规则（已配置）。
• .env.example - 环境变量模板。
• Procfile - Railway部署配置。
• railway.json - Railway平台设置。
• README.md - 本文件。

你只需要通过复制 .env.example 创建 .env 文件：

cp .env.example .env

然后使用你实际的达拉拉贾API凭证编辑 .env 文件（见上面的配置部分）。

💻 使用示例

启动服务器

本地开发（Claude桌面版）

# 激活虚拟环境
source venv/bin/activate

# 运行用于Claude桌面版的stdio服务器
python server.py

预期输出：

🚀 达拉拉贾MCP服务器启动中...
📡 回调服务器正在0.0.0.0:3000上运行
🌐 公共回调URL: http://localhost:3000/mpesa/callback
🔧 环境: 沙盒

生产/云部署

# 激活虚拟环境
source venv/bin/activate

# 运行HTTP服务器（用于Railway、Heroku等）
python server_http.py

# 或者使用gunicorn进行生产部署（如Procfile中配置）
gunicorn server_http:app --bind 0.0.0.0:$PORT --workers 2

预期输出：

🚀 达拉拉贾MCP服务器（HTTP模式）
📡 正在监听3000端口
🌐 公共URL: http://localhost:3000
🔧 环境: 沙盒

服务器组件

MCP服务器同时运行两个组件：

1. MCP协议服务器 - 通过stdio与Claude通信。
2. Flask回调服务器 - 在3000端口接收M-PESA支付通知。

选择 server.py 还是 server_http.py

本项目包含两个服务器实现，适用于不同的使用场景：

server.py - 用于本地Claude桌面版集成（stdio）

适用场景：

• 在本地机器上运行MCP服务器。
• 与Claude桌面版应用集成。
• 进行本地开发和测试。
• 使用stdio（标准输入/输出）进行MCP通信。

特性：

• 通过stdio协议与Claude桌面版通信。
• 在后台线程中运行Flask回调服务器。
• 实现了完整的MCP工具，具备所有功能。
• 最适合本地开发和测试。

使用方法：

python server.py

server_http.py - 用于远程部署（HTTP）

适用场景：

• 部署到云平台（如Railway、Heroku、AWS等）。
• 在生产环境中运行。
• 需要基于HTTP的MCP端点。
• 使用gunicorn或类似的WSGI服务器。

特性：

• 单个Flask应用，结合了MCP HTTP端点和回调。
• 暴露 /mcp/tools 和 /mcp/call_tool 端点。
• 与gunicorn配合用于生产部署。
• 与Railway的Procfile配置兼容。

使用方法：

# 使用gunicorn进行生产部署（如Procfile中配置）
gunicorn server_http:app --bind 0.0.0.0:$PORT --workers 2

# 本地测试
python server_http.py

Railway部署： Procfile 配置为使用 server_http.py 和gunicorn：

web: gunicorn server_http:app --bind 0.0.0.0:$PORT --workers 2

总结：

• 本地开发并使用Claude桌面版 → 使用 server.py。
• 云/生产部署 → 使用 server_http.py。

📚 详细文档

测试

快速测试（建议每日检查）

# 终端1：启动服务器
source venv/bin/activate
python server.py

# 终端2：运行快速测试
source venv/bin/activate
python quick_test.py

预期输出：

🔐 测试达拉拉贾认证...
✅ 认证成功！（沙盒环境）

🌐 测试回调服务器...
✅ 回调服务器正在运行！

📨 测试回调端点...
✅ 回调端点正常工作！

测试通过: 3/3
🎉 所有测试通过！

全面测试套件

python test_daraja.py

此测试运行8个测试阶段：

1. 环境变量验证
2. Python依赖项检查
3. 达拉拉贾API认证
4. MCP服务器启动
5. 回调服务器健康检查
6. 回调端点处理
7. ngrok可用性
8. STK推送格式验证

手动测试

• 测试认证

curl -X GET "https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials" \
  -H "Authorization: Basic $(echo -n 'KEY:SECRET' | base64)"

• 测试回调服务器

curl http://localhost:3000/health

• 测试回调端点

curl -X POST http://localhost:3000/mpesa/callback \
  -H "Content-Type: application/json" \
  -d '{
    "Body": {
      "stkCallback": {
        "ResultCode": 0,
        "ResultDesc": "Success"
      }
    }
  }'

与Claude桌面版集成

1. 定位配置文件

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加MCP服务器配置

{
  "mcpServers": {
    "daraja": {
      "command": "/absolute/path/to/daraja-mcp/venv/bin/python",
      "args": ["/absolute/path/to/daraja-mcp/server.py"],
      "env": {
        "DARAJA_CONSUMER_KEY": "your_consumer_key",
        "DARAJA_CONSUMER_SECRET": "your_consumer_secret",
        "DARAJA_SHORTCODE": "174379",
        "DARAJA_PASSKEY": "your_passkey",
        "DARAJA_ENV": "sandbox",
        "CALLBACK_PORT": "3000",
        "PUBLIC_URL": "https://your-ngrok-url.ngrok.io"
      }
    }
  }
}

重要提示：

• 使用绝对路径（而非相对路径）。
• 使用虚拟环境的Python：venv/bin/python。
• 使用你的ngrok HTTPS URL更新 PUBLIC_URL。

3. 重启Claude桌面版

完全退出并重新打开Claude桌面版以加载MCP服务器。

4. 验证集成

在Claude桌面版中询问：

"达拉拉贾回调服务器是否正常工作？"

Claude应回复服务器状态信息。

可用工具

配置完成后，Claude可以使用以下工具：

1. stk_push

发起STK推送支付请求。 示例：

"向0712345678发送500肯尼亚先令的支付请求，订单号为#INV-001"

参数：

• phone_number - 客户电话号码（254XXXXXXXXX或07XXXXXXXX）
• amount - 金额（肯尼亚先令，最低1）
• account_reference - 参考信息，如发票/订单号
• transaction_desc - 交易描述

2. stk_query

检查支付请求的状态。 示例：

"检查结账请求ws_CO_12345的状态"

参数：

• checkout_request_id - STK推送返回的ID

3. get_recent_payments

查看最近的支付通知。 示例：

"显示最近10笔支付"

参数：

• limit - 要检索的支付数量（默认：10，最大：50）

4. get_payment_details

获取特定支付的详细信息。 示例：

"显示收据QAR7I8K3LM的详细信息"

参数：

• checkout_request_id - 或者 -
• mpesa_receipt - M-PESA收据号码

5. mark_payment_read

将通知标记为已读。 示例：

"将支付ws_CO_12345标记为已读"

6. get_notification_summary

获取所有通知的摘要。 示例：

"我有多少未读支付？"

7. get_callback_status

检查回调服务器是否正在运行。 示例：

"回调服务器是否正常工作？"

回调设置

为什么需要ngrok（或类似的隧道服务）

问题：

• M-PESA达拉拉贾API需要 HTTPS回调（而非HTTP）。
• 萨法利通信的服务器需要从互联网访问你的回调端点。
• 你的本地开发服务器（localhost:3000）无法从互联网访问。
• 防火墙和NAT阻止外部访问你的本地机器。

解决方案： ngrok创建一个安全隧道，具有以下优点：

• ✅ 通过HTTPS将你的本地服务器暴露到互联网。
• ✅ 提供一个萨法利通信可以访问的公共URL。
• ✅ 自动处理SSL/TLS加密。
• ✅ 允许在不部署到生产环境的情况下进行实时测试。
• ✅ 在Web界面中显示所有传入请求，便于调试。

工作原理：

萨法利通信服务器 → ngrok HTTPS URL → ngrok隧道 → 你的本地服务器（localhost:3000）

本地测试使用ngrok

1. 安装ngrok

# macOS
brew install ngrok

# Linux（使用snap）
sudo snap install ngrok

# Windows
# 从https://ngrok.com/download下载
# 或者使用Chocolatey：choco install ngrok

# 或者直接从https://ngrok.com/download下载

免费注册：访问 ngrok.com 并创建一个账户以获取你的认证令牌。

2. 认证ngrok（仅首次需要）

ngrok config add-authtoken YOUR_AUTHTOKEN_HERE

3. 启动ngrok隧道

# 将HTTPS流量转发到本地端口3000
ngrok http 3000

输出：

Session Status                online
Account                       Your Name (Plan: Free)
Version                       3.x.x
Region                        United States (us)
Latency                       45ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

重要提示：复制 Forwarding 的HTTPS URL（例如，https://abc123.ngrok.io）。

4. 更新配置

更新 .env 文件中的 PUBLIC_URL：

PUBLIC_URL=https://abc123.ngrok.io

或者在Claude桌面版配置中更新ngrok URL。

注意：免费的ngrok URL每次重启ngrok时都会改变。若需要静态URL，可以升级到付费计划或使用ngrok的保留域名功能。

5. 重启服务器

# 停止服务器（Ctrl+C）
# 使用新的PUBLIC_URL重启
python server.py

6. 验证ngrok是否正常工作

• 检查ngrok Web界面：在浏览器中打开 http://localhost:4040，你将看到所有通过ngrok转发的请求，这有助于调试回调问题。
• 测试隧道：

# 通过ngrok测试健康端点
curl https://abc123.ngrok.io/health

# 应返回：
# {"status":"healthy","callback_url":"https://abc123.ngrok.io/mpesa/callback",...}

7. 保持ngrok运行

重要提示：在测试期间保持ngrok终端窗口打开。如果关闭它，隧道将停止，萨法利通信将无法访问你的回调端点。

专业提示：在单独的终端中运行ngrok，或使用 tmux 或 screen 等进程管理器：

# 使用tmux
tmux new -s ngrok
ngrok http 3000
# 按Ctrl+B然后D分离（保持在后台运行）

ngrok替代方案

如果你更喜欢其他隧道服务：

• Cloudflare Tunnel（cloudflared） - 免费，基本使用无需账户

cloudflared tunnel --url http://localhost:3000

• localtunnel - 基于npm的简单隧道

npx localtunnel --port 3000

• serveo - 基于SSH的隧道（无需安装）

ssh -R 80:localhost:3000 serveo.net

然而，建议使用ngrok，因为它：

• 最可靠和稳定。
• 有最佳的文档和社区支持。
• 提供Web界面用于请求检查。
• 易于使用和配置。

生产回调设置

对于生产环境，部署到具备以下条件的服务器：

1. 公共HTTPS端点（需要SSL证书）
2. 静态IP或域名
3. 防火墙规则，允许传入的HTTPS流量
4. 监控和日志记录

常见选项：

• 带有弹性IP的AWS EC2
• DigitalOcean Droplet
• 带有SSL的Heroku
• Google Cloud Run
• Railway（推荐 - 见下面的部署指南）

示例nginx配置：

server {
    listen 443 ssl;
    server_name api.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /mpesa/ {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Railway部署（快速启动）

Railway是部署此MCP服务器的绝佳选择，因为它：

• ✅ 自动提供HTTPS端点。
• ✅ 处理SSL证书。
• ✅ 易于配置环境变量。
• ✅ 支持从Git自动部署。
• ✅ 提供免费测试层。

Railway部署步骤

1. 创建Railway账户：访问 railway.app，使用GitHub/GitLab注册。
2. 创建新项目：点击 “New Project”，选择 “Deploy from GitHub repo”（或上传代码）。
3. 配置环境变量：在Railway仪表板中添加以下环境变量：

DARAJA_CONSUMER_KEY=your_consumer_key
DARAJA_CONSUMER_SECRET=your_consumer_secret
DARAJA_SHORTCODE=174379
DARAJA_PASSKEY=your_passkey
DARAJA_ENV=sandbox
CALLBACK_PORT=3000
PUBLIC_URL=https://your-app-name.railway.app

注意：在Railway上，应用由gunicorn提供服务，它会自动绑定到 0.0.0.0:$PORT，你无需设置 CALLBACK_HOST。 4. 部署：Railway将自动检测 Procfile 和 railway.json，Procfile 使用 server_http.py 和gunicorn，Railway将自动构建和部署。 5. 获取公共URL：Railway提供一个公共HTTPS URL（例如，https://your-app.railway.app），使用此URL更新 PUBLIC_URL 环境变量，Railway将自动重启服务。 6. 验证部署：

# 测试健康端点
curl https://your-app.railway.app/health

# 应返回：
# {"status":"healthy","callback_url":"https://your-app.railway.app/mpesa/callback",...}

重要注意事项：

• Railway自动提供HTTPS，因此生产环境无需ngrok。
• PUBLIC_URL 必须与你的Railway应用URL完全匹配。
• 对于Railway部署，使用 server_http.py（在 Procfile 中配置）。
• Railway通过 $PORT 环境变量自动处理端口绑定。

故障排除

常见问题

1. “无法获取访问令牌”

原因：

• 消费者密钥或密钥无效。
• 环境错误（沙盒与生产环境）。
• 网络连接问题。

解决方案：

# 手动测试认证
python -c "
from dotenv import load_dotenv
import os, base64, requests
load_dotenv()
key = os.getenv('DARAJA_CONSUMER_KEY')
secret = os.getenv('DARAJA_CONSUMER_SECRET')
auth = base64.b64encode(f'{key}:{secret}'.encode()).decode()
r = requests.get('https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials',
                 headers={'Authorization': f'Basic {auth}'})
print(r.json())
"

2. “回调服务器无响应”

解决方案：

# 检查3000端口是否可用
lsof -i :3000

# 杀死使用该端口的任何进程
kill -9 <PID>

# 重启服务器
python server.py

3. “Claude中找不到MCP服务器”

解决方案：

• 验证配置文件路径是否正确。
• 在配置中使用绝对路径。
• 确保虚拟环境Python路径正确。
• 检查Claude桌面版日志：帮助 → 查看日志。
• 完全重启Claude桌面版。

4. “未收到回调”

解决方案：

• 验证ngrok是否正在运行：curl https://your-url.ngrok.io/health。
• 检查 PUBLIC_URL 环境变量。
• 确保ngrok URL是HTTPS（萨法利通信要求）。
• 查看ngrok请求日志：http://localhost:4040。
• 检查防火墙设置。

5. “无效的电话号码”

解决方案：

• 使用格式：254XXXXXXXXX（不是 +254 或 07XX）。
• 沙盒环境：使用达拉拉贾门户的测试号码。
• 去除空格、破折号或特殊字符。

调试命令

# 检查服务器进程
ps aux | grep server.py

# 测试回调健康
curl http://localhost:3000/health

# 测试ngrok转发
curl https://your-ngrok-url.ngrok.io/health

# 查看Python错误
tail -f server.log

# 检查Claude日志
# macOS: ~/Library/Logs/Claude/
# Windows: %APPDATA%\Claude\logs\

获取帮助

1. 查看达拉拉贾API文档：developer.safaricom.co.ke/Documentation。
2. 查看ngrok请求检查器：http://localhost:4040。
3. 检查Claude桌面版日志。
4. 验证所有环境变量是否正确设置。
5. 独立测试每个组件。

安全最佳实践

1. 凭证管理

• ✅ 切勿将凭证提交到版本控制。
• ✅ 使用 .env 文件并配置 .gitignore。
• ✅ 定期轮换凭证。
• ✅ 沙盒和生产环境使用不同的凭证。
• ✅ 将生产密钥存储在安全的保险库中（如AWS Secrets Manager等）。

2. 网络安全

• ✅ 所有回调使用HTTPS（萨法利通信要求）。
• ✅ 实现Webhook签名验证。
• ✅ 将回调端点限制为萨法利通信的IP地址。
• ✅ 使用防火墙规则限制访问。
• ✅ 启用速率限制。

3. 应用程序安全

• ✅ 验证所有输入数据。
• ✅ 清理电话号码和金额。
• ✅ 实现请求日志记录。
• ✅ 为敏感操作添加身份验证。
• ✅ 使用特定于环境的配置。

4. 数据隐私

• ✅ 不记录敏感数据（PIN、完整卡号）。
• ✅ 在日志中屏蔽电话号码。
• ✅ 实施数据保留策略。
• ✅ 遵守数据保护法规。
• ✅ 加密数据在静止和传输过程中。

5. 监控

• ✅ 设置错误警报。
• ✅ 监控回调成功率。
• ✅ 跟踪失败的交易。
• ✅ 记录所有API调用。
• ✅ 实施健康检查。

生产部署

预部署清单

• [ ] 在沙盒环境中进行全面测试。
• [ ] 从达拉拉贾获取生产凭证。
• [ ] 设置带有SSL/TLS的生产服务器。
• [ ] 配置防火墙和安全组。
• [ ] 实施适当的日志记录和监控。
• [ ] 设置错误警报。
• [ ] 记录部署过程。
• [ ] 创建备份和恢复计划。
• [ ] 先使用小额测试。
• [ ] 配置失败时自动重启。

部署步骤

1. 准备服务器

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装Python
sudo apt install python3.10 python3.10-venv -y

# 安装nginx（用于反向代理）
sudo apt install nginx -y

# 安装supervisor（用于进程管理）
sudo apt install supervisor -y

2. 部署应用程序

# 创建应用程序目录
sudo mkdir -p /opt/daraja-mcp
sudo chown $USER:$USER /opt/daraja-mcp
cd /opt/daraja-mcp

# 克隆或复制应用程序文件
# 设置虚拟环境
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 创建生产.env文件
nano .env
# 添加生产凭证

3. 配置Supervisor

创建 /etc/supervisor/conf.d/daraja-mcp.conf：

[program:daraja-mcp]
command=/opt/daraja-mcp/venv/bin/python /opt/daraja-mcp/server.py
directory=/opt/daraja-mcp
user=www-data
autostart=true
autorestart=true
stderr_logfile=/var/log/daraja-mcp/error.log
stdout_logfile=/var/log/daraja-mcp/access.log
environment=PRODUCTION="true"

4. 配置nginx

创建 /etc/nginx/sites-available/daraja-mcp：

server {
    listen 80;
    server_name api.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

5. 启动服务

# 重新加载supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start daraja-mcp

# 启用并重启nginx
sudo ln -s /etc/nginx/sites-available/daraja-mcp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# 检查状态
sudo supervisorctl status daraja-mcp
curl https://api.yourdomain.com/health

监控和维护

# 查看日志
sudo tail -f /var/log/daraja-mcp/error.log

# 重启服务
sudo supervisorctl restart daraja-mcp

# 检查资源使用情况
htop

# 监控nginx访问日志
sudo tail -f /var/log/nginx/access.log

🔧 技术细节

达拉拉贾API端点

认证

GET https://api.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials
Authorization: Basic <base64(consumer_key:consumer_secret)>

STK推送

POST https://api.safaricom.co.ke/mpesa/stkpush/v1/processrequest
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "BusinessShortCode": "174379",
  "Password": "<base64(shortcode+passkey+timestamp)>",
  "Timestamp": "20240108143022",
  "TransactionType": "CustomerPayBillOnline",
  "Amount": 100,
  "PartyA": "254712345678",
  "PartyB": "174379",
  "PhoneNumber": "254712345678",
  "CallBackURL": "https://your-domain.com/callback",
  "AccountReference": "Order123",
  "TransactionDesc": "Payment for Order123"
}

STK查询

POST https://api.safaricom.co.ke/mpesa/stkpushquery/v1/query
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "BusinessShortCode": "174379",
  "Password": "<base64(shortcode+passkey+timestamp)>",
  "Timestamp": "20240108143022",
  "CheckoutRequestID": "ws_CO_08012024123456789"
}

MCP服务器端点

健康检查

GET http://localhost:3000/health

Response:
{
  "status": "healthy",
  "callback_url": "http://localhost:3000/mpesa/callback",
  "unread_payments": 0
}

M-PESA回调

POST http://localhost:3000/mpesa/callback
Content-Type: application/json

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "29115-34620561-1",
      "CheckoutRequestID": "ws_CO_08012024123456789",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          {"Name": "Amount", "Value": 100},
          {"Name": "MpesaReceiptNumber", "Value": "QAR7I8K3LM"},
          {"Name": "TransactionDate", "Value": 20240108143022},
          {"Name": "PhoneNumber", "Value": 254712345678}
        ]
      }
    }
  }
}

项目结构

daraja-mcp/
├── venv/                       # 虚拟环境（不在git中）
├── server.py                   # 用于本地Claude桌面版的MCP服务器（stdio）
├── server_http.py              # 用于云部署的MCP服务器（HTTP）
├── test_daraja.py             # 全面的测试套件
├── quick_test.py              # 快速验证脚本
├── Procfile                   # Railway部署配置
├── railway.json               # Railway平台配置
├── .env                       # 环境变量（不在git中）
├── .gitignore                 # Git忽略规则
├── requirements.txt           # Python依赖项
├── README.md                  # 本文件
└── docs/                      # 其他文档
    ├── DEPLOYMENT.md          # 部署指南
    ├── API.md                 # API文档
    └── TROUBLESHOOTING.md     # 扩展故障排除文档

关键文件：

• server.py - 用于与Claude桌面版进行本地开发（stdio协议）。
• server_http.py - 用于像Railway这样的云部署（HTTP端点）。
• Procfile - 定义Railway如何运行应用程序（使用 server_http.py）。
• railway.json - Railway平台配置（构建器、副本、重启策略）。

📄 许可证

本项目采用MIT许可证 - 详情请见 LICENSE 文件。

致谢

• 萨法利通信达拉拉贾API - M-PESA API平台
• Anthropic MCP - 模型上下文协议
• Flask - 用于回调的Web框架
• ngrok - 用于本地开发的安全隧道

支持

• 文档：developer.safaricom.co.ke/Documentation
• 达拉拉贾支持：support@safaricom.co.ke
• MCP文档：modelcontextprotocol.io
• 问题反馈：GitHub Issues

变更日志

v1.0.0 (2024-01-08)

• 初始版本发布
• 实现STK推送功能
• 实时回调处理
• 支付通知存储
• 自动化测试套件
• 与Claude桌面版集成
• 全面的文档

---

为M-PESA生态系统精心打造 ❤️

如有问题或需要支持，请在GitHub上提交问题或联系维护者。