# momo-mcp

**FR** — Un serveur [MCP](https://modelcontextprotocol.io) pour Mobile Money en Afrique de l'Ouest francophone. Un seul serveur, une seule intégration, pour permettre à un agent IA de faire des paiements Mobile Money — sans jongler entre les documentations de MTN MoMo, Moov Africa et Orange Money.

**EN** — An [MCP](https://modelcontextprotocol.io) server for Mobile Money in Francophone West Africa. One server, one integration, so an AI agent can make Mobile Money payments — without juggling separate docs for MTN MoMo, Moov Africa, and Orange Money.

Aujourd'hui / Currently: **MTN MoMo** (sandbox). Moov Africa et Orange Money arrivent — l'architecture est prête à les accueillir sans réécrire le serveur.

> ⚠️ **Statut : sandbox uniquement.** Testé de bout en bout sur l'environnement sandbox MTN MoMo. Pas encore audité ni utilisé en production — à valider soi-même avant tout usage avec de vrais fonds.

---

## Pourquoi ce projet / Why this project

La plupart des outils IA génériques (Stripe, PayPal...) ne couvrent pas le Mobile Money, qui reste le moyen de paiement dominant en Afrique de l'Ouest. Les rares intégrations existantes ciblent surtout l'Afrique anglophone/de l'Est. `momo-mcp` comble ce vide pour les développeurs qui construisent des agents IA (assistants d'achat, bots de paiement, outils de facturation) sur ce marché.

## Outils exposés / Tools exposed

| Outil | Description |
|---|---|
| `request_payment` | Demande un paiement à un client (Request-to-Pay). Asynchrone : renvoie `PENDING`, à suivre avec `check_payment_status`. |
| `check_payment_status` | Vérifie le statut final d'un paiement ou d'un transfert. |
| `disburse_payment` | Envoie de l'argent à un utilisateur (remboursement, salaire, payout). |
| `validate_account` | Vérifie qu'un numéro a un compte Mobile Money actif avant d'y envoyer un paiement. |

## Installation

```bash
git clone https://github.com/Tahsine/momo-mcp.git
cd momo-mcp
pip install -e .
```

### Configuration (MTN MoMo sandbox)

1. Crée un compte gratuit sur [momodeveloper.mtn.com](https://momodeveloper.mtn.com) et récupère tes clés d'abonnement **Collection** et **Disbursement**.
2. Provisionne ton API user + API key (une seule fois) :
   ```bash
   python scripts/provision_mtn.py --subscription-key TA_CLE_COLLECTION
   ```
3. Copie `.env.example` vers `.env` et remplis les valeurs obtenues.

### Utilisation avec Claude Code

```bash
claude mcp add momo-mcp -- python -m momo_mcp.server
```

### Test manuel avec l'MCP Inspector

```bash
npx @modelcontextprotocol/inspector python -m momo_mcp.server
```

## Feuille de route / Roadmap

- [x] MTN MoMo (Collection + Disbursement) — sandbox
- [ ] MTN MoMo — production
- [ ] Moov Africa
- [ ] Orange Money
- [ ] Serveur webhook optionnel pour éviter le polling manuel de `check_payment_status`

## Contact

Construit par **Tahsine** (Borrelle Dev) à Cotonou, Bénin.
Questions, retours, ou besoin d'une intégration sur-mesure (Moov, Orange, autre marché) : ouvre une issue ou contacte-moi sur [LinkedIn](https://linkedin.com/in/byborrelle) / [GitHub](https://github.com/Tahsine).

## Licence

MIT — voir [LICENSE](LICENSE).