Daraja MCP

一个设计用于将AI应用程序与Safaricom的Daraja API集成的模型上下文协议（MCP）服务器，能够实现与M-Pesa服务的无缝交互。

⚠️ 警告：不适合生产环境

该项目目前处于开发阶段，不建议在生产环境中使用。它适用于：

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

若要在生产环境中使用，请确保：

• 全面的安全测试
• 正确的错误处理
• 完整实现所有计划中的功能
• 符合Safaricom的生产要求

什么是MCP服务器？

MCP（Model Context Protocol）服务器提供了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凭据（消费者密钥和密钥）

安装

第一步：设置您的环境

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
   

第二步：设置环境变量

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 表示账单支付，SM 表示转账，SB 表示转给商家）
• identifier (str): 收款人标识符（商户号、账单号、电话号码）
• reference (str, 可选): 交易参考编号。如果未提供，则使用默认值。

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

文档处理工具

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): 用户的处理要求

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

示例：

# Example usage
prompt = await create_and_run_workflow_prompt(
    user_input="Process all PDF invoices from the invoices folder and store them in the processed folder"
)
# Returns: "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 License

致谢

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

联系方式

对于任何查询，请在 GitHub 仓库中打开一个 issue。