DarajaMCP

A Model Context Protocol (MCP) server designed to integrate AI applications with Safaricom's Daraja API, enabling seamless interaction with M-Pesa services.

⚠️ Warning: Not Production Ready

This project is currently in development and is not recommended for production use. It's designed for:

• Learning and experimentation
• Development and testing environments
• Proof of concept implementations

For production use, please ensure:

• Thorough security testing
• Proper error handling
• Complete implementation of all planned features
• Compliance with Safaricom's production requirements

MCP (Model Context Protocol) servers provide capabilities for LLMs to interact with external systems. MCP servers can provide three main types of capabilities:

• Resources: File-like data that can be read by clients (like API responses)
• Tools: Functions that can be called by the LLM (with user approval)
• Prompts: Pre-written templates that help users accomplish specific tasks

Daraja MCP specifically leverages this architecture to connect AI systems with Safaricom's Daraja M-Pesa API.

Daraja MCP is a bridge between AI, fintech, and M-Pesa, making AI-driven financial automation accessible and efficient. By standardizing the connection between LLMs (Large Language Models) and financial transactions, Daraja MCP allows AI-driven applications to process payments, retrieve transaction data, and automate financial workflows effortlessly.

• ✅ AI-Powered M-Pesa Transactions – Enable LLMs to handle B2C, C2B, and B2B payments
• ✅ Standardized Integration – MCP ensures compatibility with multiple AI tools
• ✅ Secure & Scalable – Implements OAuth authentication and supports enterprise-grade transaction handling
• ✅ Flexible Automation – AI agents can query account balances, generate invoices, and automate reconciliation

• Python 3.12
• Safaricom Daraja API Credentials (Consumer Key and Secret)

1. Install uv Package Manager

   For Mac/Linux:

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

   For Windows (PowerShell):

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

2. Clone the Repository

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

3. Create and Activate a Virtual Environment

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

   ✅ Expected Output: Your terminal prompt should change, indicating the virtual environment is activated.

4. Install Dependencies

   uv sync

1. Copy the example environment file:

   cp .env.example .env

2. Update the .env file with your actual credentials and configuration values.

Note: For development, use the sandbox environment. Switch to the production URL when ready.

1. Install Claude Desktop

   • Download and install the latest version from Claude Desktop
   • Make sure you're running the latest version

2. Configure Claude Desktop

   • Open your Claude Desktop configuration file:

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

   • Create the file if it doesn't exist

3. Add Server Configuration Choose one of the following configurations:

   Anthropic's Recommended Format

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

   Working Configuration (Tested)

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

   Note:

   • Replace /ABSOLUTE/PATH/TO/PARENT with your actual path
   • To find the full path to uv, run:

   # On MacOS/Linux
   which uv
   
   # On Windows
   where uv

4. Verify Configuration

   • Save the configuration file
   • Restart Claude Desktop
   • Look for the hammer 🔨 icon in the interface
   • Click it to see the available tools:
     • generate_access_token
     • stk_push (Future Implementation)
     • query_transaction_status (Future Implementation)
     • b2c_payment (Future Implementation)
     • account_balance (Future Implementation)

Initiate an M-Pesa STK push request to prompt the customer to authorize a payment on their mobile device.

Inputs:

• amount (int): The amount to be paid
• phone_number (int): The phone number of the customer

Returns: JSON formatted M-PESA API response

Generate a QR code for a payment request that customers can scan to make payments.

Inputs:

• merchant_name (str): Name of the company/M-Pesa Merchant Name
• transaction_reference_no (str): Transaction reference number
• amount (int): The total amount for the sale/transaction
• transaction_type (Literal["BG", "WA", "PB", "SM", "SB"]): Transaction type
• credit_party_identifier (str): Credit Party Identifier (Mobile Number, Business Number, Agent Till, Paybill, or Merchant Buy Goods)

Returns: JSON formatted M-PESA API response containing the QR code data

Generate a prompt for initiating an M-Pesa STK push payment request.

Inputs:

• phone_number (str): The phone number of the customer
• amount (int): The amount to be paid
• purpose (str): The purpose of the payment

Returns: Formatted prompt string for STK push request

Generate a prompt for creating an M-Pesa QR code payment request.

Inputs:

• merchant_name (str): Name of the merchant/business
• amount (int): Amount to be paid
• transaction_type (str): Type of transaction (BG for Buy Goods, WA for Wallet, PB for Paybill, SM for Send Money, SB for Send to Business)
• identifier (str): The recipient identifier (till number, paybill, phone number)
• reference (str, optional): Transaction reference number. If not provided, a default will be used.

Returns: Formatted prompt string for QR code generation

Create a connector from data source to unstructured server for processing.

Inputs:

• connector_name (str): The name of the source connector to create

Returns: Source connector details including name and ID

Create a connector from unstructured server to destination for data storage.

Inputs:

• connector_name (str): The name of the destination connector to create

Returns: Destination connector details including name and ID

Create a workflow to process data from source connector to destination connector.

Inputs:

• workflow_name (str): The name of the workflow to create
• source_id (str): The ID of the source connector
• destination_id (str): The ID of the destination connector

Returns: Workflow details including name, ID, status, type, sources, destinations, and schedule

Execute a workflow.

Inputs:

• workflow_id (str): The ID of the workflow to run

Returns: Workflow execution status

Get detailed information about a workflow.

Inputs:

• workflow_id (str): The ID of the workflow to get details

Returns: Workflow details including name, ID, and status

Fetch documents analyzed during workflow execution.

Inputs: None

Returns: List of analyzed documents

Generate a prompt to create and run a workflow for document processing.

Inputs:

• user_input (str): The user's processing requirements

Returns: Formatted prompt for workflow creation and execution

Example:

# 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."

Currently, no resources are available.

MIT License

• Safaricom for providing the Daraja API
• Anthropic for the MCP framework
• Contributors to the project

For any inquiries, please open an issue on the GitHub repository.