iflow-mcp_daraja 0.1.0
Add your description here
Requires Python: >=3.13

# Daraja MCP

> 🚨 **Important Notice: Repository Moved**
>
> This project has moved to a new repository. If you're looking to contribute or access the latest version, please visit:
>
> [https://github.com/paylinkmcp/paylink](https://github.com/paylinkmcp/paylink)

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

## What is an MCP Server?

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.

## Overview

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.

### Key Capabilities

- ✅ **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

## Requirements

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

## Installation

### Step 1: Setting Up Your Environment

1. **Install uv Package Manager**

   For Mac/Linux:

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

   For Windows (PowerShell):

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

2. **Clone the Repository**

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

3. **Create and Activate a Virtual Environment**

   ```bash
   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**
   ```bash
   uv sync
   ```

### Step 2: Setting up Environment Variables

1. Copy the example environment file:

   ```bash
   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.

## Usage

### Testing with Claude Desktop

1. **Install Claude Desktop**

   - Download and install the latest version from [Claude Desktop](https://claude.ai/desktop)
   - Make sure you're running the latest version

2. **Configure Claude Desktop**

   - Open your Claude Desktop configuration file:

     ```bash
     # 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

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

   #### Working Configuration (Tested)

   ```json
   {
     "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:

   ```bash
   # 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)

## Tools and Prompts

### Payment Tools

#### stk_push

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_qr_code

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

### Payment Prompts

#### stk_push_prompt

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_qr_code_prompt

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

### Document Processing Tools

#### create_source

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_destination

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_workflow

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

#### run_workflow

Execute a workflow.

**Inputs:**

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

**Returns:** Workflow execution status

#### get_workflow_details

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

Fetch documents analyzed during workflow execution.

**Inputs:** None

**Returns:** List of analyzed documents

### Prompts

#### create_and_run_workflow_prompt

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:**

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

### Resources

Currently, no resources are available.

## License

[MIT License](LICENSE)

## Acknowledgments

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

## Contact

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