Daraja MCP Server

How to use

You use Daraja MCP with an MCP client to expose M-Pesa capabilities to your AI workflows. Start the server in your development environment and load one or more MCP configurations into your client so the AI can call tools like STK pushes and balance checks. Use the provided JSON configurations as templates to wire up Claude Desktop or other MCP clients to run the local server process and discover available tools and prompts.

How to install

Prerequisites: Python 3.12 and Safaricom Daraja API credentials (Consumer Key and Consumer Secret). You also need a tool to run MCP servers locally through a wrapper like uv.

Step 1. Set up your environment

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"

Step 2. Clone the project repository

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

Step 3. Create and activate a virtual environment

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

Step 4. Install dependencies

uv sync

Step 5. Set up environment variables

Copy the example environment file and update credentials

cp .env.example .env

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

Additional configuration and usage notes

Claude Desktop configuration lets you run the MCP server locally and list available tools. You can add an MCP configuration block that points to how to start the server.

Two example configurations are shown for Claude Desktop to run the local Daraja MCP server. They use the mvn uv wrapper to start the server and point to the project folder.

Config 1 (Anthropic's Recommended Format)

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

Config 2 (Working Configuration)

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

Tools and prompts

This MCP server exposes a suite of tools and prompts for M-Pesa interactions, including STK push, QR code payments, and account balance queries. You can access these tools through your MCP client once the server is running.

Security and safety notes

This project is intended for learning and development. Ensure you perform thorough security testing, implement proper error handling, and comply with Safaricom production requirements before any production use.

Troubleshooting and notes

If you encounter issues starting the server, verify that the virtual environment is active, dependencies are installed, and the environment variables are correctly set. Use the hammer icon in Claude Desktop to verify available tools after the server starts.

What you’ll run next

The server is designed to support AI-assisted M-Pesa transactions, balance inquiries, and automated workflows with robust integration points for future features.

stk_push

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

generate_qr_code

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

create_source

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

create_destination

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

create_workflow

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

run_workflow

Execute a workflow.

get_workflow_details

Get detailed information about a workflow.

fetch_documents

Fetch documents analyzed during workflow execution.

create_and_run_workflow_prompt

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