npm package: @sparkpesa/mcp-server
Description: SparkPesa MCP Server for AI IDE integration — enables AI assistants to interact with the SparkPesa payment API
Latest version: 1.3.0

# SparkPesa MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI assistants in IDEs like **Windsurf**, **Cursor**, and **VS Code + Copilot** interact with the SparkPesa payment API.

## What It Does

The MCP server exposes SparkPesa's payment capabilities as tools that AI assistants can call directly:

### Payment Tools

| Tool | Description |
|---|---|
| `request_payment_kenya` | Collect M-Pesa payment via STK Push (KES) |
| `send_payment_kenya` | Send M-Pesa B2C payout (KES) |
| `buy_goods` | Pay to M-Pesa Till Number (KES) |
| `paybill` | Pay to M-Pesa PayBill Number (KES) |
| `request_payment_uganda` | Collect Mobile Money payment (UGX) |
| `send_payment_uganda` | Send Mobile Money payout (UGX) |

### Wallet Management Tools

| Tool | Description |
|---|---|
| `list_wallets` | List all wallets for your organization |
| `get_wallet` | Get wallet details and recent transactions |
| `create_wallet` | Create a new wallet (auto-generates 8-digit code) |
| `update_wallet` | Rename a wallet or update its description/webhook URL |
| `delete_wallet` | Deactivate a wallet (soft-delete, must have zero balance) |

### Utility Tools

| Tool | Description |
|---|---|
| `generate_signature` | Generate HMAC signature for debugging |
| `generate_webhook_handler` | Generate webhook handler code (Express, Next.js, Flask, FastAPI) |
| `generate_client_sdk` | Generate full client SDK (TypeScript, JavaScript, Python, cURL) |

It also provides **resources** (reference docs) the AI can read:
- `sparkpesa://docs/overview` — API overview, endpoints, auth
- `sparkpesa://docs/webhooks` — Webhook events, payloads, signature verification
- `sparkpesa://docs/errors` — Error codes and troubleshooting

## Setup

### 1. Install Dependencies

```bash
cd mcp-server
pnpm install
```

### 2. Build

```bash
pnpm build
```

### 3. Configure Environment

Set your SparkPesa API credentials:

```bash
export SPARKPESA_API_KEY="sk_live_your_api_key"
export SPARKPESA_API_SECRET="ss_live_your_api_secret"
export SPARKPESA_BASE_URL="https://www.sparkpesa.io/api/v1"  # optional
```

### 4. Add to Your IDE

#### Windsurf

Add to your `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "sparkpesa": {
      "command": "node",
      "args": ["/absolute/path/to/bb_merchant/mcp-server/dist/index.js"],
      "env": {
        "SPARKPESA_API_KEY": "sk_live_your_api_key",
        "SPARKPESA_API_SECRET": "ss_live_your_api_secret"
      }
    }
  }
}
```

#### Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "sparkpesa": {
      "command": "node",
      "args": ["/absolute/path/to/bb_merchant/mcp-server/dist/index.js"],
      "env": {
        "SPARKPESA_API_KEY": "sk_live_your_api_key",
        "SPARKPESA_API_SECRET": "ss_live_your_api_secret"
      }
    }
  }
}
```

#### VS Code (GitHub Copilot)

Add to your `.vscode/mcp.json`:

```json
{
  "servers": {
    "sparkpesa": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/bb_merchant/mcp-server/dist/index.js"],
      "env": {
        "SPARKPESA_API_KEY": "sk_live_your_api_key",
        "SPARKPESA_API_SECRET": "ss_live_your_api_secret"
      }
    }
  }
}
```

## Usage Examples

Once configured, you can ask your AI assistant:

- *"Collect KES 500 from 254712345678 for order ORDER-001 using wallet 12345678"*
- *"Send KES 5000 salary payment to 254712345678"*
- *"Pay KPLC electricity bill — paybill 320320, account 12345678901, KES 3500"*
- *"List all my wallets"*
- *"Create a new UGX wallet called Uganda Operations"*
- *"Rename wallet abc-123 to Main KES Wallet"*
- *"Delete the test wallet"*
- *"Generate a Next.js webhook handler for SparkPesa"*
- *"Generate a Python client SDK for SparkPesa"*
- *"What's the signature format for SparkPesa API requests?"*

The AI will use the appropriate tool or resource to fulfill the request.

## Development

```bash
# Run in development mode
pnpm dev

# Build for production
pnpm build

# Test the server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
```

## Architecture

```
mcp-server/
├── src/
│   ├── index.ts        # Entry point — creates MCP server and stdio transport
│   ├── api-client.ts   # SparkPesa API client (auth, signing, requests)
│   ├── resources.ts    # MCP resources (static reference documentation)
│   └── tools.ts        # MCP tools (payment operations + code generation)
├── package.json
├── tsconfig.json
└── README.md
```