SparkPesa MCP Server

An MCP (Model Context Protocol) 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

cd mcp-server
pnpm install

2. Build

pnpm build

3. Configure Environment

Set your SparkPesa API credentials:

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:

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

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

{
  "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

# 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