# leboncoin-mcp

Serveur [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) pour rechercher et consulter les annonces [Leboncoin](https://www.leboncoin.fr/) depuis un assistant IA.

## Crédits

Ce serveur MCP est basé sur la librairie Python **[lbc](https://github.com/etienne-hd/lbc)** par [etienne-hd](https://github.com/etienne-hd) — un client non-officiel pour l'API Leboncoin. Merci à lui pour le travail de reverse-engineering !

## Fonctionnalités

| Outil | Description |
|-------|-------------|
| `leboncoin_search_ads` | Rechercher des annonces (texte, catégorie, localisation, prix, tri…), paginé, avec mode compact par défaut |
| `leboncoin_get_ad` | Récupérer les détails complets d'une annonce |
| `leboncoin_get_user` | Consulter le profil d'un vendeur |
| `leboncoin_list_categories` | Lister les catégories disponibles |
| `leboncoin_list_regions` | Lister les régions françaises |
| `leboncoin_list_departments` | Lister les départements français |

## Installation

```bash
git clone https://github.com/arthur-c/mcp-leboncoin.git
cd mcp-leboncoin

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

> **Utilisateurs Nix :** un `shell.nix` est fourni — `nix-shell` configure le `LD_LIBRARY_PATH` et active le venv automatiquement.

## Utilisation

### Transport stdio (par défaut)

```bash
python server.py
```

C'est le mode utilisé par les clients MCP comme Cursor, Claude Desktop, etc.

### Transport SSE (HTTP)

```bash
python server.py --sse              # port 3001 par défaut
python server.py --sse --port=8080  # port personnalisé
```

## Configuration dans Cursor

Ajoutez ceci dans votre configuration MCP (`.cursor/mcp.json`) :

```json
{
  "mcpServers": {
    "leboncoin": {
      "command": "/chemin/vers/leboncoin-mcp/.venv/bin/python",
      "args": ["/chemin/vers/leboncoin-mcp/server.py"]
    }
  }
}
```

> **Important :** pointez `command` vers le Python du virtualenv (`.venv/bin/python`),
> et non vers un `python` global. Cela garantit que les dépendances (`fastmcp`, `lbc`)
> sont bien trouvées sans avoir à activer le venv, et évite tout conflit avec vos
> autres environnements Python.

## Robustesse (DataDome, rate limit, proxy)

Leboncoin est protégé par DataDome (anti-bot). Pour limiter les blocages :

- **Rate limit intégré** : les appels réseau (`search_ads`, `get_ad`, `get_user`) partagent
  une fenêtre glissante de **10 requêtes / heure**. Au-delà, l'outil renvoie un objet
  `{"error": "rate_limited", "retry_after_seconds": ...}` au lieu de risquer un bannissement.
  Ajustez `_RATE_LIMIT` / `_RATE_WINDOW` dans [`server.py`](server.py) si besoin.
- **Erreurs gracieuses** : un blocage DataDome ou une annonce introuvable renvoie un objet
  `{"error": ...}` explicite plutôt qu'une exception.
- **Réseau résidentiel** recommandé : les IP datacenter/VPS sont souvent bloquées.
- **Proxy résidentiel** (optionnel) : définissez la variable d'environnement `LBC_PROXY`
  au format `scheme://user:pass@host:port`. Exemple :

```json
{
  "mcpServers": {
    "leboncoin": {
      "command": "/chemin/vers/leboncoin-mcp/.venv/bin/python",
      "args": ["/chemin/vers/leboncoin-mcp/server.py"],
      "env": { "LBC_PROXY": "http://user:pass@host:port" }
    }
  }
}
```

## Exemples d'utilisation

Une fois le serveur connecté à votre assistant IA, vous pouvez lui demander :

- *« Cherche des vélos électriques à moins de 800€ en Île-de-France »*
- *« Montre-moi les appartements 3 pièces à Lyon »*
- *« Donne-moi les détails de l'annonce 2345678901 »*
- *« Quelles sont les catégories disponibles sur Leboncoin ? »*

## Référence des outils

### `leboncoin_search_ads`

| Paramètre | Type | Description |
|-----------|------|-------------|
| `text` | string | Texte de recherche |
| `url` | string | URL Leboncoin complète (remplace text/category/location) |
| `category` | string | Catégorie (`VEHICULES`, `IMMOBILIER`, `ELECTRONIQUE`, `LOISIRS`, `MODE`…) |
| `city` | string | Nom de ville (informatif, utilisé avec lat/lng) |
| `latitude` | float | Latitude |
| `longitude` | float | Longitude |
| `radius` | int | Rayon en mètres (défaut : 30 000 = 30 km) |
| `region` | string | Région (`ILE_DE_FRANCE`, `BRETAGNE`, `PROVENCE_ALPES_COTE_D_AZUR`…) |
| `department` | string | Département (`PARIS`, `GIRONDE`, `BOUCHES_DU_RHONE`…) |
| `price_min` | int | Prix minimum en euros |
| `price_max` | int | Prix maximum en euros |
| `sort` | string | Tri : `NEWEST`, `OLDEST`, `CHEAPEST`, `EXPENSIVE`, `RELEVANCE` |
| `ad_type` | string | `OFFER` ou `DEMAND` |
| `owner_type` | string | `PRO`, `PRIVATE` ou `ALL` |
| `shippable` | bool | Filtrer les articles livrables uniquement |
| `page` | int | Numéro de page (à partir de 1) |
| `limit` | int | Résultats par page (1-35, défaut 10) |
| `compact` | bool | `True` (défaut) : résumés légers. `False` : annonces complètes (réponse volumineuse) |

#### Format de réponse

```jsonc
{
  "pagination": {
    "page": 1, "limit": 10, "returned_count": 10,
    "max_pages": 12, "has_next_page": true, "next_page": 2
  },
  "counters": {
    "total": 120, "total_all": 120, "total_active": 118, "total_inactive": 2,
    "total_pro": 40, "total_private": 80, "total_shippable": 30
  },
  "ads": [ /* résumés (compact) ou annonces complètes */ ]
}
```

En mode `compact`, chaque annonce contient : `id`, `title`, `price`, `url`, `category`,
`location` (city/zipcode/department), `first_publication_date`, `body_excerpt` (tronqué),
`image_count` et `thumbnail`. Utilisez `leboncoin_get_ad` pour le détail complet d'une annonce.
Pour paginer, rappelez l'outil avec `page` = `pagination.next_page` tant que `has_next_page` est vrai.

### `leboncoin_get_ad`

| Paramètre | Type | Description |
|-----------|------|-------------|
| `ad_id` | string | ID numérique de l'annonce (depuis l'URL) |

### `leboncoin_get_user`

| Paramètre | Type | Description |
|-----------|------|-------------|
| `user_id` | string | ID utilisateur (format UUID) |

### `leboncoin_list_categories` / `leboncoin_list_regions` / `leboncoin_list_departments`

Aucun paramètre requis.

## Dépendances

- [lbc](https://github.com/etienne-hd/lbc) >= 1.1.2 — Client Python pour Leboncoin
- [FastMCP](https://github.com/jlowin/fastmcp) >= 3.2.0 — Framework pour serveurs MCP en Python

## Licence

[MIT](./LICENSE)