JinDaGe - daraja-mcp MCP Details

article

README

🚀 萨法利通信达拉拉贾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凭证（见下面的获取达拉拉贾凭证部分）。

运行服务器

快速启动

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

验证设置

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

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

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

运行服务器
- 本地开发并使用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

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

🚀 达拉拉贾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
}

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

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

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

# 重启服务器
python server.py

与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 文件，其中包含所有必需的环境变量。设置环境的步骤如下：

复制示例文件：

cp .env.example .env

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

# 使用nano
nano .env

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

替换占位符值 为你实际的达拉拉贾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服务器同时运行两个组件：

MCP协议服务器 - 通过stdio与Claude通信。
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个测试阶段：

环境变量验证
Python依赖项检查
达拉拉贾API认证
MCP服务器启动
回调服务器健康检查
回调端点处理
ngrok可用性
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界面用于请求检查。
易于使用和配置。

生产回调设置

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

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

常见选项：

带有弹性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部署步骤

创建Railway账户：访问 railway.app，使用GitHub/GitLab注册。
创建新项目：点击 “New Project”，选择 “Deploy from GitHub repo”（或上传代码）。
配置环境变量：在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\

获取帮助

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

安全最佳实践

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上提交问题或联系维护者。

daraja-mcp

README

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

🚀 快速开始

前提条件

安装步骤

1. 克隆仓库

2. 设置虚拟环境

3. 安装依赖

4. 配置环境变量

运行服务器

快速启动

不同场景下的运行方式

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

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

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

启动问题排查

✨ 主要特性

📦 安装指南

环境变量

项目文件

💻 使用示例

启动服务器

本地开发（Claude桌面版）

生产/云部署

服务器组件

选择 server.py 还是 server_http.py

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

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

📚 详细文档

测试

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

全面测试套件

手动测试

与Claude桌面版集成

1. 定位配置文件

2. 添加MCP服务器配置

3. 重启Claude桌面版

4. 验证集成

可用工具

1. stk_push

2. stk_query

3. get_recent_payments

4. get_payment_details

5. mark_payment_read

6. get_notification_summary

7. get_callback_status

回调设置

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

本地测试使用ngrok

1. 安装ngrok

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

3. 启动ngrok隧道

4. 更新配置

5. 重启服务器

6. 验证ngrok是否正常工作

7. 保持ngrok运行

ngrok替代方案

生产回调设置

Railway部署（快速启动）

Railway部署步骤

故障排除

常见问题

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

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

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

4. “未收到回调”

5. “无效的电话号码”

调试命令

获取帮助

安全最佳实践

1. 凭证管理

2. 网络安全

3. 应用程序安全

4. 数据隐私

5. 监控

生产部署

预部署清单

部署步骤

1. 准备服务器

选择 `server.py` 还是 `server_http.py`

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

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

1. `stk_push`

2. `stk_query`

3. `get_recent_payments`

4. `get_payment_details`

5. `mark_payment_read`

6. `get_notification_summary`

7. `get_callback_status`