### Install Safaricom Daraja MCP from Source

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/nodejs/README.md

Clone the repository, install dependencies, configure environment variables, build the project, and start the MCP server.

```bash
# Clone the repository
git clone https://github.com/Meshhack/safaricom-daraja-mcp.git
cd safaricom-daraja-mcp/nodejs

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your Daraja credentials

# Build the project
npm run build

# Start the MCP server
npm start
```

--------------------------------

### Quick Start: Run MCP Server Globally

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/nodejs/README.md

After global installation, set environment variables for Daraja credentials and start the MCP server using the `mcp-daraja` command.

```bash
# Set environment variables
export DARAJA_CONSUMER_KEY=your_consumer_key
export DARAJA_CONSUMER_SECRET=your_consumer_secret
export DARAJA_BUSINESS_SHORT_CODE=your_shortcode
export DARAJA_PASS_KEY=your_pass_key
export DARAJA_ENVIRONMENT=sandbox

# Start the MCP server
mcp-daraja
```

--------------------------------

### Node.js/Express Callback Handler Example

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/integration-guide.md

Example Express.js server setup for handling STK Push, transaction results, and timeouts from Safaricom Daraja.

```javascript
const express = require('express');
const app = express();

app.use(express.json());

// STK Push callback
app.post('/daraja/callback', (req, res) => {
    console.log('STK Push callback:', req.body);
    
    const { Body } = req.body;
    if (Body && Body.stkCallback) {
        const callback = Body.stkCallback;
        
        if (callback.ResultCode === 0) {
            // Payment successful
            console.log('Payment successful:', callback.CheckoutRequestID);
        } else {
            // Payment failed or cancelled
            console.log('Payment failed:', callback.ResultDesc);
        }
    }
    
    res.json({ ResultCode: 0, ResultDesc: "Accepted" });
});

// B2C/B2B result callback
app.post('/daraja/result', (req, res) => {
    console.log('Transaction result:', req.body);
    res.json({ ResultCode: 0, ResultDesc: "Accepted" });
});

// Timeout callback
app.post('/daraja/timeout', (req, res) => {
    console.log('Transaction timeout:', req.body);
    res.json({ ResultCode: 0, ResultDesc: "Accepted" });
});

app.listen(3000, () => {
    console.log('Callback server running on port 3000');
});
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/python/README.md

Installs all necessary packages for development, including testing and linting tools.

```bash
pip install -e .[dev]
```

--------------------------------

### Install Safaricom Daraja MCP

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/python/README.md

Clone the repository and install dependencies using pip. Configure environment variables by copying the example file and editing it with your Daraja credentials.

```bash
git clone https://github.com/meshackmusyoka/safaricom-daraja-mcp.git
cd safaricom-daraja-mcp/python

pip install -r requirements.txt

pip install -e .

cp .env.example .env
# Edit .env with your Daraja credentials

python -m mcp_daraja.server

mcp-daraja
```

--------------------------------

### Install PHP Safaricom Daraja MCP

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/README.md

Install PHP dependencies using Composer and run the Safaricom Daraja MCP server. Navigate to the PHP directory, install with Composer, and then start the server script.

```bash
cd php
composer install
php src/server.php
```

--------------------------------

### Build Safaricom Daraja MCP from Source

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/README.md

Build the Safaricom Daraja MCP from source code for Node.js. Navigate to the Node.js directory, install dependencies, build the project, and then start the server.

```bash
cd nodejs
npm install
npm run build
npm start
```

--------------------------------

### Install Daraja MCP PHP

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Steps to clone the repository, install dependencies, configure environment variables, and run the MCP server.

```bash
git clone https://github.com/meshackmusyoka/safaricom-daraja-mcp.git
cd safaricom-daraja-mcp/php

composer install

cp .env.example .env
# Edit .env with your Daraja credentials

./bin/mcp-daraja

php bin/mcp-daraja
```

--------------------------------

### Install Node.js/TypeScript Daraja MCP

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/integration-guide.md

Navigate to the Node.js directory, install dependencies, copy the environment file, and build the project.

```bash
cd nodejs
npm install
cp .env.example .env
npm run build
```

--------------------------------

### Install Python Daraja MCP

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/integration-guide.md

Navigate to the Python directory, install requirements, and copy the environment file.

```bash
cd python
pip install -r requirements.txt
cp .env.example .env
```

--------------------------------

### Basic JavaScript MCP Client Example

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

A basic JavaScript example demonstrating how to create and use an MCP client with the Daraja service. It includes setting up the transport, connecting the client, listing available tools, and calling the STK Push tool.

```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create transport
const transport = new StdioClientTransport({
  command: "mcp-daraja",
  env: {
    DARAJA_CONSUMER_KEY: "your_consumer_key_here",
    DARAJA_CONSUMER_SECRET: "your_consumer_secret_here",
    DARAJA_BUSINESS_SHORT_CODE: "your_business_shortcode",
    DARAJA_PASS_KEY: "your_pass_key_here",
    DARAJA_ENVIRONMENT: "sandbox",
    DARAJA_INITIATOR_NAME: "your_initiator_name",
    DARAJA_INITIATOR_PASSWORD: "your_initiator_password",
  },
});

// Create client
const client = new Client(
  { name: "daraja-client", version: "1.0.0" },
  { capabilities: {} }
);

// Connect and use
await client.connect(transport);

// List available tools
const tools = await client.request({
  method: "tools/list",
  params: {},
});

console.log("Available tools:", tools.result.tools);

// Call STK Push tool
const stkResult = await client.request({
  method: "tools/call",
  params: {
    name: "daraja_stk_push",
    arguments: {
      amount: 100,
      phone_number: "254708374149",
      callback_url: "https://your-domain.com/callback",
      account_reference: "TEST123",
      transaction_desc: "Test Payment",
    },
  },
});

console.log("STK Push result:", stkResult.result);
```

--------------------------------

### Install PHP Daraja MCP

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/integration-guide.md

Navigate to the PHP directory, install dependencies using Composer, and copy the environment file.

```bash
cd php
composer install
cp .env.example .env
```

--------------------------------

### Install Claude Code CLI

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Install the Claude Code CLI package globally. Verify the installation using the `claude --version` command.

```bash
# Verify Claude Code installation
claude --version

# If not installed:
npm install -g @anthropic/claude-code
```

--------------------------------

### Configuration and Environment Setup

Source: https://context7.com/meshhack/safaricom-daraja-mcp/llms.txt

Details on setting up Daraja API credentials and environment variables for both sandbox and production environments.

```APIDOC
## Configuration and Environment Setup

### Description
This section outlines the necessary environment variables and configuration files required to set up the Safaricom Daraja MCP server for integration.

### Environment Variables
All Daraja API implementations require the following environment variables to be configured:

- **DARAJA_CONSUMER_KEY**: Your Daraja API consumer key.
- **DARAJA_CONSUMER_SECRET**: Your Daraja API consumer secret.
- **DARAJA_BUSINESS_SHORT_CODE**: Your business short code (e.g., '174379' for sandbox).
- **DARAJA_PASS_KEY**: Your Daraja API pass key.
- **DARAJA_ENVIRONMENT**: The environment to use ('sandbox' or 'production').

For specific operations like B2C, B2B, Balance, Status, and Reversal, the following additional variables are required:

- **DARAJA_INITIATOR_NAME**: The initiator's name for the transaction.
- **DARAJA_INITIATOR_PASSWORD**: The encrypted initiator's password.

### Example Bash Configuration
```bash
export DARAJA_CONSUMER_KEY="your_consumer_key"
export DARAJA_CONSUMER_SECRET="your_consumer_secret"
export DARAJA_BUSINESS_SHORT_CODE="174379"
export DARAJA_PASS_KEY="bfb279f9aa9bdbcf158e97dd71a467cd..."
export DARAJA_ENVIRONMENT="sandbox"
export DARAJA_INITIATOR_NAME="testapi"
export DARAJA_INITIATOR_PASSWORD="your_encrypted_password"
```

### Claude Desktop Configuration (`~/.config/claude/claude_desktop_config.json`)
This JSON configuration file can be used to set up the Daraja MCP server within Claude Desktop.

```json
{
  "mcpServers": {
    "daraja": {
      "command": "mcp-daraja",
      "env": {
        "DARAJA_CONSUMER_KEY": "your_key",
        "DARAJA_CONSUMER_SECRET": "your_secret",
        "DARAJA_BUSINESS_SHORT_CODE": "174379",
        "DARAJA_PASS_KEY": "your_pass_key",
        "DARAJA_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```
```

--------------------------------

### Install Python Safaricom Daraja MCP

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/README.md

Install Python dependencies and run the Safaricom Daraja MCP module. Navigate to the Python directory, install requirements, and then execute the module.

```bash
cd python
pip install -r requirements.txt
python -m mcp_daraja
```

--------------------------------

### Install Safaricom Daraja MCP CLI

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/README.md

Install the Safaricom Daraja MCP command-line interface globally using npm. Ensure Node.js 18+ is installed. Set environment variables for API credentials before running the CLI.

```bash
# Global installation
npm install -g @meshark/safaricom-daraja-mcp

# Set environment variables and run
export DARAJA_CONSUMER_KEY=your_key
export DARAJA_CONSUMER_SECRET=your_secret
export DARAJA_BUSINESS_SHORT_CODE=your_shortcode
export DARAJA_PASS_KEY=your_pass_key
export DARAJA_ENVIRONMENT=sandbox
mcp-daraja
```

--------------------------------

### Verify Claude CLI MCP Server Setup

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Verify the Daraja MCP server setup in Claude CLI by listing available servers and testing the connection.

```bash
# List available MCP servers
claude mcp list

# Test the connection
claude mcp test daraja
```

--------------------------------

### Expose Local Server with Ngrok

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/examples/README.md

Installs ngrok globally and exposes a local development server (e.g., on port 3000) to the internet via HTTPS. Useful for testing callback URLs.

```bash
# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use the HTTPS URL for callbacks
# Example: https://abc123.ngrok.io/callback
```

--------------------------------

### Install Safaricom Daraja MCP via npm

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/nodejs/README.md

Install the package globally to use as a CLI or locally in your project.

```bash
# Install globally to use as CLI
npm install -g @meshark/safaricom-daraja-mcp

# Or install locally in your project
npm install @meshark/safaricom-daraja-mcp
```

--------------------------------

### Docker Compose for Daraja MCP

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Defines a Docker Compose setup for running the Daraja MCP service. It specifies the Node.js image, working directory, volume mounts, environment variables, and the command to install and run the Daraja MCP.

```yaml
version: "3.8"
services:
  daraja-mcp:
    image: node:18-alpine
    working_dir: /app
    volumes:
      - ./:/app
    environment:
      - DARAJA_CONSUMER_KEY=${DARAJA_CONSUMER_KEY}
      - DARAJA_CONSUMER_SECRET=${DARAJA_CONSUMER_SECRET}
      - DARAJA_BUSINESS_SHORT_CODE=${DARAJA_BUSINESS_SHORT_CODE}
      - DARAJA_PASS_KEY=${DARAJA_PASS_KEY}
      - DARAJA_ENVIRONMENT=sandbox
      - DARAJA_INITIATOR_NAME=${DARAJA_INITIATOR_NAME}
      - DARAJA_INITIATOR_PASSWORD=${DARAJA_INITIATOR_PASSWORD}
    command: >
      sh -c "npm install -g @meshark/safaricom-daraja-mcp && 
             mcp-daraja"
    stdin_open: true
    tty: true
```

--------------------------------

### B2C Payment Example

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/nodejs/README.md

Initiate a Business-to-Consumer payment. This requires a command ID, recipient's phone number, and URLs for timeout and results.

```javascript
// Tool call to daraja_b2c_payment
{
  "amount": 500,
  "party_b": "254708374149",
  "command_id": "BusinessPayment",
  "remarks": "Salary payment",
  "queue_timeout_url": "https://yourdomain.com/timeout",
  "result_url": "https://yourdomain.com/result"
}
```

--------------------------------

### Install Safaricom Daraja MCP CLI

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Install the Safaricom Daraja MCP npm package globally to use it with command-line tools.

```bash
npm install -g @meshark/safaricom-daraja-mcp
```

--------------------------------

### STK Push Payment Example

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/nodejs/README.md

Use this for initiating an STK Push payment. Ensure the phone number is valid and the callback URL is correctly configured.

```javascript
// Tool call to daraja_stk_push
{
  "amount": 100,
  "phone_number": "254708374149",
  "callback_url": "https://yourdomain.com/callback",
  "account_reference": "TEST123",
  "transaction_desc": "Payment Test"
}
```

--------------------------------

### QR Code Test Request (Bash)

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/examples/README.md

Example cURL command to test the QR code generation endpoint.

```bash
curl -X POST http://localhost:8080/generate-qr \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_name": "Test Store",
    "amount": 500,
    "trx_code": "BG",
    "ref_no": "QR123",
    "cpi": "373132"
  }'
```

--------------------------------

### Perform B2C Payment

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Example of tool call parameters for initiating a Business to Customer (B2C) payment.

```php
// Tool call to daraja_b2c_payment
[
    "amount" => 500,
    "party_b" => "254708374149",
    "command_id" => "BusinessPayment",
    "remarks" => "Salary payment",
    "queue_timeout_url" => "https://yourdomain.com/timeout",
    "result_url" => "https://yourdomain.com/result"
]
```

--------------------------------

### STK Push Test Request (Bash)

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/examples/README.md

Example cURL command to test the STK Push payment initiation endpoint.

```bash
curl -X POST http://localhost:3000/pay \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "phoneNumber": "254708374149",
    "reference": "TEST123",
    "description": "Test Payment"
  }'
```

--------------------------------

### Run Node.js/TypeScript Daraja Server

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/integration-guide.md

Start the Daraja MCP server for Node.js/TypeScript applications.

```bash
npm start
```

--------------------------------

### Initiate STK Push Payment

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Example of tool call parameters for initiating an M-Pesa Express (STK Push) payment.

```php
// Tool call to daraja_stk_push
[
    "amount" => 100,
    "phone_number" => "254708374149",
    "callback_url" => "https://yourdomain.com/callback",
    "account_reference" => "TEST123",
    "transaction_desc" => "Payment Test"
]
```

--------------------------------

### B2C Payment Test Request (Bash)

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/examples/README.md

Example cURL command to test the B2C payment initiation endpoint.

```bash
curl -X POST http://localhost:8000/send-money \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_phone": "254708374149",
    "amount": 1000,
    "command_id": "BusinessPayment",
    "remarks": "Test B2C payment",
    "occasion": "Testing"
  }'
```

--------------------------------

### Verify MCP Version

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Check the currently installed version of the mcp-daraja command-line tool.

```bash
# Verify version
mcp-daraja --version
```

--------------------------------

### Add Daraja MCP Server via Claude CLI Wizard

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Use the Claude CLI wizard to add the Daraja MCP server. This method is recommended for beginners as it guides you through the process.

```bash
# Add the Daraja MCP server
claude mcp add daraja --package @meshark/safaricom-daraja-mcp
```

--------------------------------

### Query Payment Status Example

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/nodejs/README.md

Use this to check the status of a payment using the Checkout Request ID. This is useful for confirming transaction outcomes.

```javascript
// Tool call to daraja_stk_query
{
  "checkout_request_id": "ws_CO_191220231234567890"
}
```

--------------------------------

### MCP Client Integration with Custom MCP Client

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/nodejs/README.md

Integrate with the Daraja MCP server using the `@modelcontextprotocol/sdk` in a custom client. This example demonstrates initiating an M-Pesa Express payment.

```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'mcp-daraja'
});

const client = new Client(
  { name: 'daraja-client', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(transport);

// Make a payment
const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'daraja_stk_push',
    arguments: {
      amount: 100,
      phone_number: '254708374149',
      callback_url: 'https://your-domain.com/callback',
      account_reference: 'ORDER123',
      transaction_desc: 'Payment'
    }
  }
});
```

--------------------------------

### Initialize MCP Client and Call Daraja STK Push

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/integration-guide.md

Demonstrates how to set up the MCP client with a StdioClientTransport and initiate an STK Push transaction with Daraja.

```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Create client and transport
const transport = new StdioClientTransport({
  command: 'node',
  args: ['/path/to/daraja/server.js']
});

const client = new Client(
  { name: 'daraja-client', version: '1.0.0' },
  { capabilities: {} }
);

// Connect to server
await client.connect(transport);

// Call a tool
const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'daraja_stk_push',
    arguments: {
      amount: 100,
      phone_number: '254708374149',
      callback_url: 'https://yourdomain.com/callback',
      account_reference: 'TEST123',
      transaction_desc: 'Test Payment'
    }
  }
});

console.log('STK Push result:', result);
```

--------------------------------

### Development Scripts

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/nodejs/README.md

Common npm scripts for building, developing, testing, and linting the project. Run these commands from the project's root directory.

```bash
# Build TypeScript
npm run build
```

```bash
# Start development with watch mode
npm run dev
```

```bash
# Run tests
npm test
```

```bash
# Lint code
npm run lint
```

```bash
# Fix linting issues
npm run lint:fix
```

--------------------------------

### Execute All Quality Checks with Composer

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Run a comprehensive suite of quality checks, including tests, style checks, and static analysis, using Composer's quality script. This is recommended before pushing changes.

```bash
composer quality
```

--------------------------------

### Project Structure

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/nodejs/README.md

Overview of the project's directory and file structure. Key files include the server entry point, Daraja API client, and type definitions.

```tree
nodejs/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── daraja-client.ts  # Daraja API client
│   ├── types.ts          # TypeScript definitions
│   └── schemas.ts        # Zod validation schemas
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```

--------------------------------

### Perform Static Analysis with Composer

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Run static analysis tools on the project code using Composer's analyse script. This helps detect potential bugs and code quality issues.

```bash
composer analyse
```

--------------------------------

### Run Project Tests with Composer

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Execute all defined tests for the project using the Composer test script. Ensure all tests pass before contributing changes.

```bash
composer test
```

--------------------------------

### Daraja API Error Handling

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Example of catching a custom DarajaException and logging relevant error details using Monolog.

```php
try {
    $result = $client->stkPush(...);
} catch (DarajaException $e) {
    $logger->error('API Error', [
        'code' => $e->getDarajaCode(),
        'status' => $e->getHttpStatus(),
        'response' => $e->getResponse()
    ]);
}
```

--------------------------------

### Initiate B2C Payment (Python)

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/examples/README.md

Initiates a Business to Customer payment. Requires FastAPI and httpx. Use for payroll or bulk payments.

```python
# B2C payment for salary
salary_data = {
    "recipient_phone": employee.phone,
    "amount": employee.salary,
    "command_id": "SalaryPayment",
    "remarks": f"Salary for {employee.name}",
    "occasion": f"{current_month} Salary"
}

response = requests.post('/send-money', json=salary_data)
```

--------------------------------

### Project Structure Overview

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/python/README.md

This Python project is organized with a main package 'mcp_daraja' containing server, client, and types modules. It also includes configuration files for dependencies, build, environment, and documentation.

```text
python/
├── mcp_daraja/
│   ├── __init__.py       # Package initialization
│   ├── server.py         # MCP server implementation
│   ├── client.py         # Daraja API client
│   └── types.py          # Pydantic models and types
├── requirements.txt      # Dependencies
├── pyproject.toml       # Build configuration
├── .env.example         # Environment template
└── README.md            # This file
```

--------------------------------

### Enable Claude Debug Mode

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Enable debug mode for Claude CLI to get more verbose output, useful for troubleshooting.

```bash
# Enable debug mode
CLAUDE_DEBUG=1 claude <command>
```

--------------------------------

### STKPushRequest with Type Safety

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Example of a request Data Transfer Object (DTO) enforcing type safety and basic validation for the Amount property.

```php
class STKPushRequest
{
    public function __construct(
        public readonly string $BusinessShortCode,
        public readonly int $Amount,
        // ... other typed properties
    )
    {
        if ($Amount <= 0) {
            throw new InvalidArgumentException('Amount must be positive');
        }
    }
}
```

--------------------------------

### Query STK Push Payment Status

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Example of tool call parameters for querying the status of an STK Push payment using its checkout request ID.

```php
// Tool call to daraja_stk_query
[
    "checkout_request_id" => "ws_CO_191220231234567890"
]
```

--------------------------------

### Test MCP Server Connection

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Send a JSON-RPC request to the MCP server to test if it's running and responsive. This command should return a list of available tools.

```bash
# Test if server starts
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | mcp-daraja
```

--------------------------------

### Enable MCP Support in VS Code

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Configure VS Code settings to enable MCP support and agent functionality. This involves creating or editing the `.vscode/settings.json` file.

```json
{
  "chat.mcp.enabled": true,
  "chat.agent.enabled": true,
  "mcp.discovery.enabled": true
}
```

--------------------------------

### Check Code Style with Composer

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Verify the project's code style against defined standards using Composer's cs-check script. This helps maintain code consistency.

```bash
composer cs-check
```

--------------------------------

### Configure Daraja API Credentials

Source: https://context7.com/meshhack/safaricom-daraja-mcp/llms.txt

Sets up required Daraja API credentials as environment variables for sandbox or production environments. Additional variables are needed for B2C, B2B, Balance, Status, and Reversal operations.

```bash
# Required environment variables
export DARAJA_CONSUMER_KEY="your_consumer_key"
export DARAJA_CONSUMER_SECRET="your_consumer_secret"
export DARAJA_BUSINESS_SHORT_CODE="174379"  # Sandbox shortcode
export DARAJA_PASS_KEY="bfb279f9aa9bdbcf158e97dd71a467cd..."
export DARAJA_ENVIRONMENT="sandbox"  # or "production"

# Required for B2C, B2B, Balance, Status, Reversal operations
export DARAJA_INITIATOR_NAME="testapi"
export DARAJA_INITIATOR_PASSWORD="your_encrypted_password"
```

```json
# Claude Desktop configuration (~/.config/claude/claude_desktop_config.json)
{
  "mcpServers": {
    "daraja": {
      "command": "mcp-daraja",
      "env": {
        "DARAJA_CONSUMER_KEY": "your_key",
        "DARAJA_CONSUMER_SECRET": "your_secret",
        "DARAJA_BUSINESS_SHORT_CODE": "174379",
        "DARAJA_PASS_KEY": "your_pass_key",
        "DARAJA_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```

--------------------------------

### Manage API Credentials Securely

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/examples/README.md

Demonstrates using environment variables to store sensitive API credentials like consumer keys and secrets. Avoids hardcoding credentials directly in the code.

```javascript
// Use environment variables
const config = {
    consumerKey: process.env.DARAJA_CONSUMER_KEY,
    consumerSecret: process.env.DARAJA_CONSUMER_SECRET,
    // Never hardcode credentials
};
```

--------------------------------

### Configure Safaricom Daraja MCP for Claude Desktop

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/README.md

JSON configuration for setting up the Safaricom Daraja MCP server within Claude Desktop. This includes the command to run and environment variables for API authentication.

```json
{
  "mcpServers": {
    "daraja": {
      "command": "mcp-daraja",
      "env": {
        "DARAJA_CONSUMER_KEY": "your_key",
        "DARAJA_CONSUMER_SECRET": "your_secret",
        "DARAJA_BUSINESS_SHORT_CODE": "your_shortcode",
        "DARAJA_PASS_KEY": "your_pass_key",
        "DARAJA_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```

--------------------------------

### Production Environment Configuration

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/integration-guide.md

Configuration details for the Safaricom Daraja MCP production environment, requiring live credentials.

```env
DARAJA_ENVIRONMENT=production
DARAJA_CONSUMER_KEY=your_production_key
DARAJA_CONSUMER_SECRET=your_production_secret
DARAJA_BUSINESS_SHORT_CODE=your_live_shortcode
DARAJA_PASS_KEY=your_live_pass_key
```

--------------------------------

### Environment Variables for Docker Compose

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Provides a sample `.env` file for Docker Compose, defining the necessary environment variables for the Daraja MCP service. These variables should be replaced with actual credentials.

```env
DARAJA_CONSUMER_KEY=your_consumer_key_here
DARAJA_CONSUMER_SECRET=your_consumer_secret_here
DARAJA_BUSINESS_SHORT_CODE=your_business_shortcode
DARAJA_PASS_KEY=your_pass_key_here
DARAJA_INITIATOR_NAME=your_initiator_name
DARAJA_INITIATOR_PASSWORD=your_initiator_password
```

--------------------------------

### Configure Daraja MCP Server for VS Code

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Set up the Daraja MCP server configuration in VS Code by creating a `.vscode/mcp.json` file. This file specifies the server type, command, and environment variables required for the Daraja server.

```json
{
  "servers": {
    "daraja": {
      "type": "stdio",
      "command": "mcp-daraja",
      "env": {
        "DARAJA_CONSUMER_KEY": "${env:DARAJA_CONSUMER_KEY}",
        "DARAJA_CONSUMER_SECRET": "${env:DARAJA_CONSUMER_SECRET}",
        "DARAJA_BUSINESS_SHORT_CODE": "${env:DARAJA_BUSINESS_SHORT_CODE}",
        "DARAJA_PASS_KEY": "${env:DARAJA_PASS_KEY}",
        "DARAJA_ENVIRONMENT": "${env:DARAJA_ENVIRONMENT}",
        "DARAJA_INITIATOR_NAME": "${env:DARAJA_INITIATOR_NAME}",
        "DARAJA_INITIATOR_PASSWORD": "${env:DARAJA_INITIATOR_PASSWORD}"
      }
    }
  }
}
```

--------------------------------

### Configure Daraja MCP Server in Claude Desktop

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Add the Daraja MCP server configuration to Claude Desktop's `claude_desktop_config.json` file. Ensure all environment variables are correctly set.

```json
{
  "mcpServers": {
    "daraja": {
      "command": "mcp-daraja",
      "env": {
        "DARAJA_CONSUMER_KEY": "your_consumer_key_here",
        "DARAJA_CONSUMER_SECRET": "your_consumer_secret_here",
        "DARAJA_BUSINESS_SHORT_CODE": "your_business_shortcode",
        "DARAJA_PASS_KEY": "your_pass_key_here",
        "DARAJA_ENVIRONMENT": "sandbox",
        "DARAJA_INITIATOR_NAME": "your_initiator_name",
        "DARAJA_INITIATOR_PASSWORD": "your_initiator_password"
      }
    }
  }
}
```

--------------------------------

### Initiate STK Push Payment (Node.js)

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/examples/README.md

Initiates an STK Push payment. Requires Express.js and the Daraja SDK. Use for e-commerce checkouts.

```javascript
const initiatePayment = async (orderData) => {
    const response = await fetch('/pay', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            amount: orderData.total,
            phoneNumber: orderData.customerPhone,
            reference: orderData.orderId,
            description: `Order #${orderData.orderId}`
        })
    });
    
    return response.json();
};
```

--------------------------------

### Environment Considerations

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/api-reference.md

Information on using the Daraja API in different environments, including Sandbox and Production.

```APIDOC
## Environment Considerations

### Sandbox
- Use test credentials and phone numbers
- All transactions are simulated
- No real money involved

### Production
- Requires Safaricom go-live approval
- Real money transactions
- Enhanced security requirements
- Proper SSL certificates required for callbacks
```

--------------------------------

### Configure Daraja API Credentials

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/php/README.md

Environment variables required for connecting to the Daraja API. Ensure to replace placeholder values with your actual credentials.

```env
DARAJA_CONSUMER_KEY=your_consumer_key
DARAJA_CONSUMER_SECRET=your_consumer_secret
DARAJA_BUSINESS_SHORT_CODE=your_shortcode
DARAJA_PASS_KEY=your_pass_key
DARAJA_ENVIRONMENT=sandbox
DARAJA_INITIATOR_NAME=your_initiator_name
DARAJA_INITIATOR_PASSWORD=your_initiator_password
```

--------------------------------

### Rate Limits and Best Practices

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/api-reference.md

Guidelines for using the Daraja API effectively, including token management, rate limits, callback URL requirements, and phone number formatting.

```APIDOC
## Rate Limits and Best Practices

1. **Token Management**: Tokens are automatically managed with 1-hour expiration
2. **Rate Limits**: Respect Safaricom's API rate limits (varies by endpoint)
3. **Callback URLs**: Always use HTTPS for callback URLs
4. **Phone Numbers**: Use Kenyan format (254XXXXXXXX) for best compatibility
5. **Error Handling**: Implement proper error handling in your application
6. **Logging**: Monitor API responses for debugging and audit trails
```

--------------------------------

### Run Python Daraja Server

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/integration-guide.md

Execute the Daraja MCP server module for Python applications.

```bash
python -m mcp_daraja.server
```

--------------------------------

### Daraja Configuration with Type Safety

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/python/README.md

Demonstrates how to configure the Daraja client using Pydantic models for type safety. Ensure you import the necessary types like STKPushInput, Environment, and DarajaConfig.

```python
from mcp_daraja.types import STKPushInput, Environment, DarajaConfig

# Full type hints throughout
config = DarajaConfig(
    consumer_key="key",
    consumer_secret="secret",
    business_short_code="123456",
    pass_key="pass_key",
    environment=Environment.SANDBOX
)
```

--------------------------------

### View Claude MCP Logs

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Command to view logs specifically for the MCP client within the Claude environment.

```bash
# View logs
claude logs mcp
```

--------------------------------

### Initiate B2C Payment

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/python/README.md

Use this tool call to perform a Business to Customer payment. Specify the amount, recipient's phone number (party_b), command ID, remarks, and URLs for timeout and result notifications.

```json
{
    "amount": 500,
    "party_b": "254708374149",
    "command_id": "BusinessPayment",
    "remarks": "Salary payment",
    "queue_timeout_url": "https://yourdomain.com/timeout",
    "result_url": "https://yourdomain.com/result"
}
```

--------------------------------

### Add Daraja Server Configuration in Cursor IDE

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Configure the Daraja MCP server within the Cursor IDE settings. This JSON configuration specifies the command to run the Daraja server and its environment variables.

```json
{
  "mcpServers": {
    "daraja": {
      "command": "mcp-daraja",
      "args": [],
      "env": {
        "DARAJA_CONSUMER_KEY": "your_consumer_key_here",
        "DARAJA_CONSUMER_SECRET": "your_consumer_secret_here",
        "DARAJA_BUSINESS_SHORT_CODE": "your_business_shortcode",
        "DARAJA_PASS_KEY": "your_pass_key_here",
        "DARAJA_ENVIRONMENT": "sandbox",
        "DARAJA_INITIATOR_NAME": "your_initiator_name",
        "DARAJA_INITIATOR_PASSWORD": "your_initiator_password"
      }
    }
  }
}
```

--------------------------------

### Sort Imports with isort

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/python/README.md

Sorts imports alphabetically within the mcp_daraja directory using isort.

```bash
isort mcp_daraja/
```

--------------------------------

### MCP Desktop Client Daraja Configuration

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/integration-guide.md

JSON configuration for integrating the Safaricom Daraja MCP server with MCP Desktop Clients, specifying command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "daraja": {
      "command": "node",
      "args": ["/path/to/safaricom-daraja-mcp/nodejs/dist/index.js"],
      "env": {
        "DARAJA_CONSUMER_KEY": "your_key",
        "DARAJA_CONSUMER_SECRET": "your_secret",
        "DARAJA_BUSINESS_SHORT_CODE": "your_shortcode",
        "DARAJA_PASS_KEY": "your_pass_key",
        "DARAJA_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```

--------------------------------

### Configure Daraja MCP Server Directly in Claude CLI

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/docs/mcp-integration-guide.md

Manually edit the Claude CLI configuration file to add the Daraja MCP server. This method is suitable for advanced users.

```json
{
  "mcp": {
    "servers": {
      "daraja": {
        "command": "mcp-daraja",
        "env": {
          "DARAJA_CONSUMER_KEY": "your_consumer_key_here",
          "DARAJA_CONSUMER_SECRET": "your_consumer_secret_here",
          "DARAJA_BUSINESS_SHORT_CODE": "your_business_shortcode",
          "DARAJA_PASS_KEY": "your_pass_key_here",
          "DARAJA_ENVIRONMENT": "sandbox",
          "DARAJA_INITIATOR_NAME": "your_initiator_name",
          "DARAJA_INITIATOR_PASSWORD": "your_initiator_password"
        }
      }
    }
  }
}
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/meshhack/safaricom-daraja-mcp/blob/main/python/README.md

Executes all tests defined in the project using the Pytest framework.

```bash
pytest
```