Daraja MCP

一个模型上下文协议 (MCP) 服务器，旨在将 AI 应用程序与 Safaricom 的 Daraja API 集成，从而实现与 M-Pesa 服务的无缝交互。

⚠️ 警告：尚未准备好用于生产环境

此项目目前正在开发中，不建议用于生产环境。它专为以下目的而设计：

• 学习和实验
• 开发和测试环境
• 概念验证实现

对于生产用途，请确保：

• 彻底的安全测试
• 适当的错误处理
• 所有计划功能的完整实现
• 符合 Safaricom 的生产要求

什么是 MCP 服务器？

MCP（模型上下文协议）服务器为 LLM 提供与外部系统交互的能力。 MCP 服务器可以提供三种主要类型的能力：

• 资源：可以被客户端读取的类似文件的数据（例如 API 响应）
• 工具：可以被 LLM 调用的函数（需要用户批准）
• 提示：预先编写的模板，可帮助用户完成特定任务

Daraja MCP 专门利用此架构将 AI 系统与 Safaricom 的 Daraja M-Pesa API 连接起来。

概述

Daraja MCP 是 AI、金融科技和 M-Pesa 之间的桥梁，使 AI 驱动的金融自动化变得可访问且高效。 通过标准化 LLM（大型语言模型）和金融交易之间的连接，Daraja MCP 允许 AI 驱动的应用程序处理付款、检索交易数据并轻松自动化金融工作流程。

主要功能

• ✅ AI 驱动的 M-Pesa 交易 – 使 LLM 能够处理 B2C、C2B 和 B2B 付款
• ✅ 标准化集成 – MCP 确保与多种 AI 工具的兼容性
• ✅ 安全且可扩展 – 实施 OAuth 身份验证并支持企业级交易处理
• ✅ 灵活的自动化 – AI 代理可以查询账户余额、生成发票和自动对账

要求

• Python 3.12
• Safaricom Daraja API 凭据（Consumer Key 和 Secret）

安装

步骤 1：设置您的环境

1. 安装 uv 包管理器

   对于 Mac/Linux：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   对于 Windows (PowerShell)：

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. 克隆存储库

   git clone https://github.com/jameskanyiri/DarajaMCP.git
   cd DarajaMCP
   

3. 创建并激活虚拟环境

   uv venv
   source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
   

   ✅ 预期输出：您的终端提示符应更改，表明虚拟环境已激活。

4. 安装依赖项

   uv sync
   

步骤 2：设置环境变量

1. 复制示例环境变量文件：

   cp .env.example .env
   

2. 使用您的实际凭据和配置值更新 .env 文件。

注意：对于开发，请使用沙盒环境。 准备就绪后切换到生产 URL。

用法

使用 Claude Desktop 进行测试

1. 安装 Claude Desktop

   • 从 Claude Desktop 下载并安装最新版本
   • 确保您运行的是最新版本

2. 配置 Claude Desktop

   • 打开您的 Claude Desktop 配置文件：

     # 在 MacOS/Linux 上
     code ~/Library/Application\ Support/Claude/claude_desktop_config.json
     
     # 在 Windows 上
     code %APPDATA%\Claude\claude_desktop_config.json
     

   • 如果文件不存在，请创建它

3. 添加服务器配置 选择以下配置之一：

   Anthropic 推荐的格式

   {
     "mcpServers": {
       "daraja": {
         "command": "uv",
         "args": [
           "--directory",
           "/ABSOLUTE/PATH/TO/PARENT/FOLDER/DarajaMCP",
           "run",
           "main.py"
         ]
       }
     }
   }
   

   可用的配置（已测试）

   {
     "mcpServers": {
       "DarajaMCP": {
         "command": "/ABSOLUTE/PATH/TO/PARENT/.local/bin/uv",
         "args": [
           "--directory",
           "/ABSOLUTE/PATH/TO/PARENT/FOLDER/DarajaMCP",
           "run",
           "main.py"
         ]
       }
     }
   }
   

   注意：

   • 将 /ABSOLUTE/PATH/TO/PARENT 替换为您的实际路径
   • 要查找 uv 的完整路径，请运行：

   # 在 MacOS/Linux 上
   which uv
   
   # 在 Windows 上
   where uv
   

4. 验证配置

   • 保存配置文件
   • 重新启动 Claude Desktop
   • 在界面中查找锤子 🔨 图标
   • 单击它以查看可用的工具：
     • generate_access_token
     • stk_push（未来实现）
     • query_transaction_status（未来实现）
     • b2c_payment（未来实现）
     • account_balance（未来实现）

工具和提示

支付工具

stk_push

发起 M-Pesa STK 推送请求，提示客户授权在其移动设备上付款。

输入：

• amount (int)：要支付的金额
• phone_number (int)：客户的电话号码

返回： JSON 格式的 M-PESA API 响应

generate_qr_code

生成支付请求的二维码，客户可以扫描该二维码进行支付。

输入：

• merchant_name (str)：公司/M-Pesa 商户名称
• transaction_reference_no (str)：交易参考编号
• amount (int)：销售/交易的总金额
• transaction_type (Literal["BG", "WA", "PB", "SM", "SB"])：交易类型
• credit_party_identifier (str)：贷方标识符（手机号码、商业号码、代理收款机、Paybill 或商户购买商品）

返回： 包含二维码数据的 JSON 格式的 M-PESA API 响应

支付提示

stk_push_prompt

生成用于发起 M-Pesa STK 推送支付请求的提示。

输入：

• phone_number (str)：客户的电话号码
• amount (int)：要支付的金额
• purpose (str)：付款目的

返回： 用于 STK 推送请求的格式化提示字符串

generate_qr_code_prompt

生成用于创建 M-Pesa 二维码支付请求的提示。

输入：

• merchant_name (str)：商户/企业名称
• amount (int)：要支付的金额
• transaction_type (str)：交易类型（BG 代表购买商品，WA 代表钱包，PB 代表 Paybill，SM 代表汇款，SB 代表发送给企业）
• identifier (str)：收款人标识符（收款机号码、paybill、电话号码）
• reference (str, optional)：交易参考编号。 如果未提供，将使用默认值。

返回： 用于生成二维码的格式化提示字符串

文档处理工具

create_source

创建从数据源到非结构化服务器的连接器以进行处理。

输入：

• connector_name (str)：要创建的源连接器的名称

返回： 源连接器详细信息，包括名称和 ID

create_destination

创建从非结构化服务器到目标的数据存储连接器。

输入：

• connector_name (str)：要创建的目标连接器的名称

返回： 目标连接器详细信息，包括名称和 ID

create_workflow

创建工作流程以处理从源连接器到目标连接器的数据。

输入：

• workflow_name (str)：要创建的工作流程的名称
• source_id (str)：源连接器的 ID
• destination_id (str)：目标连接器的 ID

返回： 工作流程详细信息，包括名称、ID、状态、类型、源、目标和计划

run_workflow

执行工作流程。

输入：

• workflow_id (str)：要运行的工作流程的 ID

返回： 工作流程执行状态

get_workflow_details

获取有关工作流程的详细信息。

输入：

• workflow_id (str)：要获取详细信息的工作流程的 ID

返回： 工作流程详细信息，包括名称、ID 和状态

fetch_documents

获取在工作流程执行期间分析的文档。

输入： 无

返回： 分析的文档列表

提示

create_and_run_workflow_prompt

生成用于创建和运行文档处理工作流程的提示。

输入：

• user_input (str)：用户的处理要求

返回： 用于工作流程创建和执行的格式化提示

示例：

# 示例用法
prompt = await create_and_run_workflow_prompt(
    user_input="Process all PDF invoices from the invoices folder and store them in the processed folder"
)
# 返回："The user wants to achieve Process all PDF invoices from the invoices folder and store them in the processed folder. Assist them by creating a source connector and a destination connector, then setting up the workflow and executing it."

资源

目前，没有可用的资源。

许可证

MIT 许可证

致谢

• Safaricom 提供 Daraja API
• Anthropic 提供 MCP 框架
• 项目贡献者

联系方式

如有任何疑问，请在 GitHub 存储库上打开一个 issue。