Safaricom Daraja MCP Server

A Model Context Protocol (MCP) server that integrates Safaricom's M-PESA Daraja API with Claude, enabling natural language payment processing and real-time transaction notifications.

🌟 Features

• STK Push Payments: Initiate M-PESA payment requests through natural language

• Real-time Callbacks: Automatic payment notification handling with Flask server

• Payment Tracking: Store and query payment history with read/unread status

• Natural Language Interface: Interact with M-PESA through Claude conversations

• Sandbox Testing: Full support for Daraja sandbox environment

• Automated Testing: Comprehensive test suite for validation

Related MCP server: Daraja MCP

📋 Table of Contents

• Prerequisites

• Installation

• Configuration

• Getting Daraja Credentials

• Usage

• Testing

• Integrating with Claude Desktop

• Claude Desktop and Railway

• Available Tools

• Callback Setup

• Troubleshooting

• Security Best Practices

• Production Deployment

• API coverage vs Postman

• API Reference

• Project Structure

• Contributing

• License

Prerequisites

• Python 3.10+ installed on your system

• Daraja API Account - Register at developer.safaricom.co.ke

• ngrok (optional, for testing callbacks) - Download from ngrok.com

• Claude Desktop (optional, for MCP integration)

Installation

1. Clone the Repository

# Clone the repository
git clone https://github.com/mboya/daraja-mcp.git
cd daraja-mcp

# Or if you already have the repository, navigate to it
cd daraja-mcp

2. Set Up Virtual Environment

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# macOS/Linux:
source venv/bin/activate

# Windows:
venv\Scripts\activate

You should see (venv) in your terminal prompt.

3. Install Dependencies

# Install all required packages from requirements.txt
pip install -r requirements.txt

This will install:

• mcp - Model Context Protocol server

• requests - HTTP library for API calls

• flask - Web framework for callback server

• python-dotenv - Environment variable management

• gunicorn - WSGI HTTP server (for production deployment)

4. Configure Environment Variables

Create a .env file in the project root directory. The repository includes a .env.example file as a template.

Quick Setup:

# Copy the example file
cp .env.example .env

# Edit the .env file with your actual credentials
# Use your preferred text editor (nano, vim, code, etc.)
nano .env

Then replace the placeholder values with your actual Daraja API credentials (see Getting Daraja Credentials).

Configuration

Environment Variables

Copy .env.example to .env and fill in your credentials. Key variables:

Never commit .env. For production, set variables in your hosting dashboard (Railway, etc.).

Getting Daraja Credentials

1. Register on Daraja Portal

1. Visit developer.safaricom.co.ke

2. Create an account

3. Verify your email

2. Create an App

1. Navigate to "My Apps" → "Create New App"

2. Select APIs:

   • Lipa Na M-PESA Online

   • M-PESA Express (STK Push)

3. Submit your app

4. Get your credentials:

   • Consumer Key

   • Consumer Secret

   • Passkey (in app details)

3. Sandbox Test Credentials

For testing, use these sandbox values:

• Business Short Code: 174379 (default sandbox)

• Passkey: Check your app details on Daraja portal

• Test Phone Numbers: 254708374149 (check Daraja docs for updated test numbers)

• Test PIN: Varies by sandbox version (usually simulated automatically)

4. Production Credentials

1. Test thoroughly in sandbox

2. Apply for production access through Daraja portal

3. Complete KYC and business verification

4. Receive production credentials

5. Update .env with production values and set DARAJA_ENV=production

Usage

Run the server

Verify the server:

curl http://127.0.0.1:3000/health

Both server.py and server_http.py share the same callback routes and MCP tools via daraja_core.py. server.py talks to Claude over stdio and runs Flask in a background thread; server_http.py is a single Flask app for deployment.

For real Safaricom callbacks in sandbox, set PUBLIC_URL to an HTTPS URL (ngrok locally). See Callback setup.

Then configure Claude Desktop.

Testing

All tests are in test_daraja.py.

Exit code 0 on pass, 1 on failure. Warnings (e.g. IMSI sandbox 404) do not fail CI.

Optional: DARAJA_TEST_PHONE (default 254708374149), DARAJA_B2C_TEST_AMOUNT (default 10).

GitHub Actions CI

Workflow: .github/workflows/ci.yml (push/PR to main, workflow_dispatch).

The live-sandbox job runs on workflow_dispatch or push to main; it runs live tests only when DARAJA_CONSUMER_KEY and DARAJA_CONSUMER_SECRET repository secrets are set (otherwise the job skips those steps).

Integrating with Claude Desktop

1. Locate Configuration File

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add MCP Server Configuration

{
  "mcpServers": {
    "daraja": {
      "command": "/absolute/path/to/daraja-mcp/venv/bin/python",
      "args": ["/absolute/path/to/daraja-mcp/server.py"],
      "env": {
        "DARAJA_CONSUMER_KEY": "your_consumer_key",
        "DARAJA_CONSUMER_SECRET": "your_consumer_secret",
        "DARAJA_SHORTCODE": "174379",
        "DARAJA_PASSKEY": "your_passkey",
        "DARAJA_ENV": "sandbox",
        "CALLBACK_PORT": "3000",
        "PUBLIC_URL": "https://your-ngrok-url.ngrok.io"
      }
    }
  }
}

Important:

• Use absolute paths (not relative)

• Use virtual environment's Python: venv/bin/python

• Update PUBLIC_URL with your ngrok HTTPS URL

3. Restart Claude Desktop

Completely quit and reopen Claude Desktop to load the MCP server.

4. Verify Integration

In Claude Desktop, ask:

"Is the Daraja callback server working?"

Claude should respond with server status information.

Claude Desktop and Railway

This section explains how Claude Desktop relates to a Railway deployment. Read this before pointing PUBLIC_URL at Railway while running Claude locally.

Two servers, two transports

Claude Desktop does not connect to Railway as a native MCP server today. It expects a local command (server.py), not https://your-app.railway.app/mcp/call_tool.

Railway’s HTTP endpoints are a REST-style tool API, not the full MCP stream Claude Desktop uses over stdio (or remote MCP URL/SSE).

Callbacks must hit the same process as Claude

STK payments and async callbacks are stored in memory in the running server process.

Rule: The host in PUBLIC_URL must be the same instance that handles MCP tools and stores payments.

Recommended setups

A — Claude Desktop + local server (recommended for chatting with Claude)

1. Configure Claude with server.py (see Integrating with Claude Desktop).

2. Run ngrok (or similar): ngrok http 3000.

3. Set PUBLIC_URL in Claude’s env to the ngrok HTTPS URL (or in .env if you load it locally).

4. Skip Railway for Claude, or use Railway only for unrelated HTTP integrations.

B — Railway only (no Claude Desktop)

1. Deploy via Procfile (gunicorn server_http:app).

2. Set Railway variables (see Railway Deployment), especially:

   PUBLIC_URL=https://your-service.up.railway.app

3. Verify: curl https://your-service.up.railway.app/health

4. Call tools with HTTP:

   curl -X POST https://your-service.up.railway.app/mcp/call_tool \
     -H "Content-Type: application/json" \
     -d '{"name":"get_notification_summary","arguments":{}}'

5. Register Safaricom callback URLs using your Railway domain (see Callback routes).

C — Railway for callbacks + Claude (common mistake)

Setting Claude’s local PUBLIC_URL to Railway looks convenient but breaks payment tracking in Claude: STK/B2C results land on Railway, while get_recent_payments reads the local store.

Use setup A instead, or setup B without Claude until shared storage or remote MCP is implemented.

Railway env vars (Claude-free deployment)

Initiator and IoT variables are optional; see .env.example.

Available Tools

Once configured, Claude can use these tools:

1. stk_push

Initiate an STK Push payment request.

Example:

"Send a payment request for 500 KES to 0712345678 for order #INV-001"

Parameters:

• phone_number - Customer phone (254XXXXXXXXX or 07XXXXXXXX)

• amount - Amount in KES (minimum 1)

• account_reference - Reference like invoice/order number

• transaction_desc - Description of transaction

2. stk_query

Check the status of a payment request.

Example:

"Check the status of checkout request ws_CO_12345"

Parameters:

• checkout_request_id - ID returned from STK push

3. get_recent_payments

View recent payment notifications.

Example:

"Show me the last 10 payments"

Parameters:

• limit - Number of payments to retrieve (default: 10, max: 50)

4. get_payment_details

Get details of a specific payment.

Example:

"Show me details for receipt QAR7I8K3LM"

Parameters:

• checkout_request_id - Or -

• mpesa_receipt - M-PESA receipt number

5. mark_payment_read

Mark a notification as read.

Example:

"Mark payment ws_CO_12345 as read"

6. get_notification_summary

Get summary of all notifications.

Example:

"How many unread payments do I have?"

7. get_callback_status

Check if callback server is running.

Example:

"Is the callback server working?"

Additional tools (B2C, B2B, C2B, Ratiba, Pull, IMSI, IoT) are listed under API coverage vs Postman.

Phase 1 — B2C, B2B, C2B, balance, status, reversal

Callback Setup

Safaricom requires HTTPS callback URLs reachable from the internet. Localhost works for simulated webhooks (python test_daraja.py --callbacks); use a tunnel or deployed host for real STK/B2C results.

Automated tests can start ngrok for you (--live, --b2c, --all).

Why You Need ngrok (or Similar Tunneling Service)

The Problem:

• M-PESA Daraja API requires HTTPS callbacks (not HTTP)

• Safaricom's servers need to reach your callback endpoint from the internet

• Your local development server (localhost:3000) is not accessible from the internet

• Firewalls and NAT prevent external access to your local machine

The Solution: ngrok creates a secure tunnel that:

• ✅ Exposes your local server to the internet via HTTPS

• ✅ Provides a public URL that Safaricom can reach

• ✅ Automatically handles SSL/TLS encryption

• ✅ Allows real-time testing without deploying to production

• ✅ Shows all incoming requests in a web interface for debugging

How It Works:

Safaricom Servers → ngrok HTTPS URL → ngrok Tunnel → Your Local Server (localhost:3000)

Local Testing with ngrok

1. Install ngrok

# macOS
brew install ngrok

# Linux (using snap)
sudo snap install ngrok

# Windows
# Download from https://ngrok.com/download
# Or use Chocolatey: choco install ngrok

# Or download directly from https://ngrok.com/download

Sign up for free: Visit ngrok.com and create an account to get your authtoken.

2. Authenticate ngrok (First Time Only)

ngrok config add-authtoken YOUR_AUTHTOKEN_HERE

3. Start ngrok Tunnel

# Forward HTTPS traffic to your local port 3000
ngrok http 3000

Output:

Session Status                online
Account                       Your Name (Plan: Free)
Version                       3.x.x
Region                        United States (us)
Latency                       45ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Important: Copy the Forwarding HTTPS URL (e.g., https://abc123.ngrok.io)

4. Update Configuration

Update PUBLIC_URL in your .env file:

PUBLIC_URL=https://abc123.ngrok.io

Or update Claude Desktop config with the ngrok URL.

Note: Free ngrok URLs change each time you restart ngrok. For a static URL, upgrade to a paid plan or use ngrok's reserved domains feature.

5. Restart Server

# Stop the server (Ctrl+C)
# Restart with new PUBLIC_URL
python server.py

6. Verify ngrok is Working

Check ngrok web interface:

• Open http://localhost:4040 in your browser

• You'll see all requests being forwarded through ngrok

• Useful for debugging callback issues

Test the tunnel:

# Test health endpoint through ngrok
curl https://abc123.ngrok.io/health

# Should return:
# {"status":"healthy","callback_url":"https://abc123.ngrok.io/mpesa/callback",...}

7. Keep ngrok Running

Important: Keep the ngrok terminal window open while testing. If you close it, the tunnel stops and Safaricom won't be able to reach your callback endpoint.

Pro Tip: Run ngrok in a separate terminal or use a process manager like tmux or screen:

# Using tmux
tmux new -s ngrok
ngrok http 3000
# Press Ctrl+B then D to detach (keeps running in background)

ngrok Alternatives

If you prefer other tunneling services:

• Cloudflare Tunnel (cloudflared) - Free, no account needed for basic use

  cloudflared tunnel --url http://localhost:3000

• localtunnel - Simple npm-based tunnel

  npx localtunnel --port 3000

• serveo - SSH-based tunnel (no installation)

  ssh -R 80:localhost:3000 serveo.net

However, ngrok is recommended because:

• Most reliable and stable

• Best documentation and community support

• Web interface for request inspection

• Easy to use and configure

Production Callback Setup

For production, deploy to a server with:

1. Public HTTPS endpoint (SSL certificate required)

2. Static IP or domain name

3. Firewall rules allowing incoming HTTPS traffic

4. Monitoring and logging

Popular options:

• AWS EC2 with Elastic IP

• DigitalOcean Droplet

• Heroku with SSL

• Google Cloud Run

• Railway (recommended - see deployment guide below)

Example nginx configuration:

server {
    listen 443 ssl;
    server_name api.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /mpesa/ {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Railway Deployment (Quick Start)

Railway is an excellent choice for deploying this MCP server because it:

• ✅ Provides HTTPS endpoints automatically

• ✅ Handles SSL certificates

• ✅ Easy environment variable configuration

• ✅ Automatic deployments from Git

• ✅ Free tier available for testing

Railway Deployment Steps

1. Create Railway Account

   • Visit railway.app

   • Sign up with GitHub/GitLab

2. Create New Project

   • Click "New Project"

   • Select "Deploy from GitHub repo" (or upload code)

3. Configure Environment Variables In Railway dashboard, add these environment variables:

   DARAJA_CONSUMER_KEY=your_consumer_key
   DARAJA_CONSUMER_SECRET=your_consumer_secret
   DARAJA_SHORTCODE=174379
   DARAJA_PASSKEY=your_passkey
   DARAJA_ENV=sandbox
   CALLBACK_PORT=3000
   PUBLIC_URL=https://your-app-name.railway.app

   Note: On Railway, the app is served by gunicorn which binds to 0.0.0.0:$PORT automatically; you don't need to set CALLBACK_HOST.

4. Deploy

   • Railway will automatically detect Procfile and railway.json

   • The Procfile uses server_http.py with gunicorn

   • Railway will build and deploy automatically

5. Get Your Public URL

   • Railway provides a public HTTPS URL (e.g., https://your-app.railway.app)

   • Update PUBLIC_URL environment variable with this URL

   • Railway will restart the service automatically

6. Verify Deployment

   # Test health endpoint
   curl https://your-app.railway.app/health
   
   # Should return:
   # {"status":"healthy","callback_url":"https://your-app.railway.app/mpesa/callback",...}

Important Notes:

• Railway automatically provides HTTPS, so no ngrok needed in production

• The PUBLIC_URL must match your Railway app URL exactly

• Use server_http.py (configured in Procfile) for Railway deployments

• Railway handles port binding automatically via $PORT environment variable

Troubleshooting

Startup

Common Issues

1. "Failed to get access token"

Causes:

• Invalid Consumer Key or Secret

• Wrong environment (sandbox vs production)

• Network connectivity issues

Solutions:

# Test authentication manually
python -c "
from dotenv import load_dotenv
import os, base64, requests
load_dotenv()
key = os.getenv('DARAJA_CONSUMER_KEY')
secret = os.getenv('DARAJA_CONSUMER_SECRET')
auth = base64.b64encode(f'{key}:{secret}'.encode()).decode()
r = requests.get('https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials',
                 headers={'Authorization': f'Basic {auth}'})
print(r.json())
"

2. "Callback server not responding"

Solutions:

# Check if port 3000 is available
lsof -i :3000

# Kill any process using the port
kill -9 <PID>

# Restart server
python server.py

3. "MCP server not found in Claude"

Solutions:

• Verify config file path is correct

• Use absolute paths in configuration

• Ensure virtual environment Python path is correct

• Check Claude Desktop logs: Help → View Logs

• Restart Claude Desktop completely

4. "No callbacks received"

Solutions:

• Verify ngrok is running: curl https://your-url.ngrok.io/health

• Check PUBLIC_URL environment variable

• Ensure ngrok URL is HTTPS (required by Safaricom)

• View ngrok request logs: http://localhost:4040

• Check firewall settings

5. "Invalid phone number"

Solutions:

• Use format: 254XXXXXXXXX (not +254 or 07XX)

• Sandbox: Use test numbers from Daraja portal

• Remove spaces, dashes, or special characters

Debug Commands

# Check server process
ps aux | grep server.py

# Test callback health
curl http://localhost:3000/health

# Test ngrok forwarding
curl https://your-ngrok-url.ngrok.io/health

# View Python errors
tail -f server.log

# Check Claude logs
# macOS: ~/Library/Logs/Claude/
# Windows: %APPDATA%\Claude\logs\

Getting Help

1. Check Daraja API documentation: developer.safaricom.co.ke/Documentation

2. Review ngrok request inspector: http://localhost:4040

3. Check Claude Desktop logs

4. Verify all environment variables are set correctly

5. Test each component independently

Security Best Practices

1. Credential Management

• ✅ Never commit credentials to version control

• ✅ Use .env files with .gitignore

• ✅ Rotate credentials regularly

• ✅ Use different credentials for sandbox and production

• ✅ Store production secrets in secure vaults (AWS Secrets Manager, etc.)

2. Network Security

• ✅ Use HTTPS for all callbacks (required by Safaricom)

• ✅ Implement webhook signature verification

• ✅ Restrict callback endpoint to Safaricom IPs

• ✅ Use firewall rules to limit access

• ✅ Enable rate limiting

3. Application Security

• ✅ Validate all input data

• ✅ Sanitize phone numbers and amounts

• ✅ Implement request logging

• ✅ Add authentication for sensitive operations

• ✅ Use environment-specific configurations

4. Data Privacy

• ✅ Don't log sensitive data (PINs, full card numbers)

• ✅ Mask phone numbers in logs

• ✅ Implement data retention policies

• ✅ Comply with data protection regulations

• ✅ Encrypt data at rest and in transit

5. Monitoring

• ✅ Set up error alerting

• ✅ Monitor callback success rates

• ✅ Track failed transactions

• ✅ Log all API calls

• ✅ Implement health checks

Production Deployment

Pre-deployment Checklist

• Thoroughly tested in sandbox environment

• Obtained production credentials from Daraja

• Set up production server with SSL/TLS

• Configured firewall and security groups

• Implemented proper logging and monitoring

• Set up error alerting

• Documented deployment process

• Created backup and recovery plan

• Tested with small amounts first

• Configured auto-restart on failure

Deployment Steps

1. Prepare Server

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python
sudo apt install python3.10 python3.10-venv -y

# Install nginx (for reverse proxy)
sudo apt install nginx -y

# Install supervisor (for process management)
sudo apt install supervisor -y

2. Deploy Application

# Create application directory
sudo mkdir -p /opt/daraja-mcp
sudo chown $USER:$USER /opt/daraja-mcp
cd /opt/daraja-mcp

# Clone or copy application files
# Set up virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Create production .env
nano .env
# Add production credentials

3. Configure Supervisor

Create /etc/supervisor/conf.d/daraja-mcp.conf:

[program:daraja-mcp]
command=/opt/daraja-mcp/venv/bin/python /opt/daraja-mcp/server.py
directory=/opt/daraja-mcp
user=www-data
autostart=true
autorestart=true
stderr_logfile=/var/log/daraja-mcp/error.log
stdout_logfile=/var/log/daraja-mcp/access.log
environment=PRODUCTION="true"

4. Configure nginx

Create /etc/nginx/sites-available/daraja-mcp:

server {
    listen 80;
    server_name api.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

5. Start Services

# Reload supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start daraja-mcp

# Enable and restart nginx
sudo ln -s /etc/nginx/sites-available/daraja-mcp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# Check status
sudo supervisorctl status daraja-mcp
curl https://api.yourdomain.com/health

Monitoring and Maintenance

# View logs
sudo tail -f /var/log/daraja-mcp/error.log

# Restart service
sudo supervisorctl restart daraja-mcp

# Check resource usage
htop

# Monitor nginx access
sudo tail -f /var/log/nginx/access.log

Postman collection (API reference)

The repo includes Safaricom’s official Postman collection as the source-of-truth checklist for Daraja endpoints:

Use this collection when adding MCP tools: each request maps to a Daraja API product. Coverage vs this server is summarized in API coverage below.

API coverage vs Postman

Initiator APIs need DARAJA_INITIATOR_NAME, DARAJA_INITIATOR, and DARAJA_SECURITY_CREDENTIAL in .env.

Callback routes (prefix with your HTTPS PUBLIC_URL):

Phase 2 — M-PESA Ratiba (standing orders)

Frequency codes: 1 once, 2 daily, 3 weekly, 4 monthly, 5 bi-monthly, 6 quarterly, 7 half-year, 8 yearly (or aliases like monthly, weekly).

Dates: start_date and end_date as yyyymmdd (e.g. 20260101).

Phase 3 — Pull API & SFC Verify

Pull query dates: YYYY-MM-DD H:MM:SS (e.g. 2024-08-04 8:36:00).

Phase 4 — IMSI / SWAP

Sandbox note: 404 Not found usually means the IMSI product is not enabled on your Daraja app, or the test MSISDN is not provisioned for IMSI. Enable IMSI CheckATI in the developer portal, confirm sandbox test numbers, and set DARAJA_TEST_PHONE if needed.

Phase 5 — IoT SIM Portal

API Reference

Daraja API Endpoints

Authentication

GET https://api.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials
Authorization: Basic <base64(consumer_key:consumer_secret)>

STK Push

POST https://api.safaricom.co.ke/mpesa/stkpush/v1/processrequest
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "BusinessShortCode": "174379",
  "Password": "<base64(shortcode+passkey+timestamp)>",
  "Timestamp": "20240108143022",
  "TransactionType": "CustomerPayBillOnline",
  "Amount": 100,
  "PartyA": "254712345678",
  "PartyB": "174379",
  "PhoneNumber": "254712345678",
  "CallBackURL": "https://your-domain.com/callback",
  "AccountReference": "Order123",
  "TransactionDesc": "Payment for Order123"
}

STK Query

POST https://api.safaricom.co.ke/mpesa/stkpushquery/v1/query
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "BusinessShortCode": "174379",
  "Password": "<base64(shortcode+passkey+timestamp)>",
  "Timestamp": "20240108143022",
  "CheckoutRequestID": "ws_CO_08012024123456789"
}

MCP Server Endpoints

Health Check

GET http://localhost:3000/health

Response:
{
  "status": "healthy",
  "environment": "sandbox",
  "callback_url": "http://localhost:3000/mpesa/callback",
  "callback_urls": { "stk": "...", "b2c_result": "...", "ratiba": "...", "pull": "..." },
  "unread_payments": 0,
  "unread_callbacks": 0
}

M-PESA Callback

POST http://localhost:3000/mpesa/callback
Content-Type: application/json

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "29115-34620561-1",
      "CheckoutRequestID": "ws_CO_08012024123456789",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          {"Name": "Amount", "Value": 100},
          {"Name": "MpesaReceiptNumber", "Value": "QAR7I8K3LM"},
          {"Name": "TransactionDate", "Value": 20240108143022},
          {"Name": "PhoneNumber", "Value": 254712345678}
        ]
      }
    }
  }
}

Project Structure

daraja-mcp/
├── venv/                       # Virtual environment (not in git)
├── daraja_core.py              # Shared Daraja client, callbacks, MCP tools
├── daraja_iot.py               # IMSI and IoT SIM Portal APIs (Phases 4–5)
├── server.py                   # MCP server for local Claude Desktop (stdio)
├── server_http.py              # MCP server for cloud deployment (HTTP)
├── test_daraja.py             # Unified test suite (see Testing)
├── .github/workflows/ci.yml   # CI: platform, webhooks, gunicorn, optional live
├── Procfile                   # Railway: gunicorn server_http:app
├── railway.json               # Railway platform configuration
├── .env.example               # Environment template (copy to .env)
├── requirements.txt           # Python dependencies
├── README.md                  # This file
└── Safaricom APIs.postman_collection.json  # Postman reference (optional local copy)

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Setup

Follow Installation, then run python test_daraja.py --platform before opening a PR.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Safaricom Daraja API - M-PESA API platform

• Anthropic MCP - Model Context Protocol

• Flask - Web framework for callbacks

• ngrok - Secure tunneling for local development

Support

• Documentation: developer.safaricom.co.ke/Documentation

• Daraja Support: support@safaricom.co.ke

• MCP Documentation: modelcontextprotocol.io

• Issues: GitHub Issues

Changelog

v1.0.0 (2024-01-08)

• Initial release

• STK Push implementation

• Real-time callback handling

• Payment notification storage

• Automated testing suite

• Claude Desktop integration

• Comprehensive documentation

Made with ❤️ for the M-PESA ecosystem

For questions or support, please open an issue on GitHub or contact the maintainers.