# cinetpay-mcp

MCP Server for CinetPay — integrate mobile money payments into Claude, Cursor, and any MCP-compatible AI assistant.

## What it does

This MCP server connects your AI assistant to the CinetPay API, enabling natural language interactions with mobile money payments across Africa.

**Ask your assistant:**
- "What's the balance on the CI account?"
- "Check the status of payment ORDER-12345"
- "Initialize a payment of 5000 XOF for customer jean@email.com"
- "Send 1000 XOF to +2250707000001 via Orange Money"
- "What payment methods are available in Senegal?"

## Available Tools

| Tool | Description |
|------|-------------|
| `get_balance` | Get account balance for a country |
| `check_payment_status` | Check payment status by ID |
| `initialize_payment` | Create a new payment (returns payment URL) |
| `create_transfer` | Send money to a phone number |
| `check_transfer_status` | Check transfer status by ID |
| `list_payment_methods` | List operators for a country |
| `list_configured_countries` | Show configured countries |

## Installation

### Claude Code

```bash
claude mcp add cinetpay -- npx cinetpay-mcp
```

Then set your environment variables in `.claude/settings.json`:

```json
{
  "mcpServers": {
    "cinetpay": {
      "command": "npx",
      "args": ["cinetpay-mcp"],
      "env": {
        "CINETPAY_API_KEY_CI": "sk_test_...",
        "CINETPAY_API_PASSWORD_CI": "your_password"
      }
    }
  }
}
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cinetpay": {
      "command": "npx",
      "args": ["cinetpay-mcp"],
      "env": {
        "CINETPAY_API_KEY_CI": "sk_test_...",
        "CINETPAY_API_PASSWORD_CI": "your_password"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "cinetpay": {
      "command": "npx",
      "args": ["cinetpay-mcp"],
      "env": {
        "CINETPAY_API_KEY_CI": "sk_test_...",
        "CINETPAY_API_PASSWORD_CI": "your_password"
      }
    }
  }
}
```

## Configuration

### Environment Variables

#### Multi-country (recommended)

Set credentials per country using the pattern `CINETPAY_API_KEY_{COUNTRY}` / `CINETPAY_API_PASSWORD_{COUNTRY}`:

```bash
# Côte d'Ivoire
CINETPAY_API_KEY_CI=sk_test_...
CINETPAY_API_PASSWORD_CI=your_password

# Sénégal
CINETPAY_API_KEY_SN=sk_test_...
CINETPAY_API_PASSWORD_SN=your_password

# Cameroun
CINETPAY_API_KEY_CM=sk_live_...
CINETPAY_API_PASSWORD_CM=your_password
```

#### Single country

```bash
CINETPAY_API_KEY=sk_test_...
CINETPAY_API_PASSWORD=your_password
CINETPAY_COUNTRY=CI  # Default: CI
```

#### Optional

```bash
CINETPAY_BASE_URL=https://api.cinetpay.co  # Default: auto-detected from key prefix
CINETPAY_FORCE_IPV4=true                    # Force IPv4 DNS resolution
```

### Environments

| Key prefix | API URL | Environment |
|---|---|---|
| `sk_test_...` | `https://api.cinetpay.net` | Sandbox |
| `sk_live_...` | `https://api.cinetpay.co` | Production |

The server auto-detects the environment from your API key prefix.

## Supported Countries

| Country | Code | Operators |
|---------|------|-----------|
| Côte d'Ivoire | CI | Orange Money, Moov, MTN, Wave |
| Sénégal | SN | Orange Money, Free, Expresso, Wave |
| Cameroun | CM | Orange Money, MTN |
| Burkina Faso | BF | Orange Money, Moov, Wave |
| Mali | ML | Orange Money, Moov |
| Togo | TG | Moov, TMoney |
| Guinée | GN | Orange Money, MTN |
| Bénin | BJ | Moov, MTN |
| RD Congo | CD | Orange Money, Airtel, M-Pesa, Africell |
| Niger | NE | Airtel, Moov, Zamani |

## Security

- API credentials are read from environment variables only — never hardcoded
- The server uses the [cinetpay-js](https://www.npmjs.com/package/cinetpay-js) SDK with all its security features:
  - HTTPS enforcement
  - Credential sanitization in logs
  - ES2022 private fields
  - Environment mismatch detection
- Each user runs their own MCP server instance with their own credentials

## Support

For CinetPay API questions: **support@cinetpay.com**

## License

MIT