leboncoin-mcp

Serveur MCP (Model Context Protocol) pour rechercher et consulter les annonces Leboncoin depuis un assistant IA.

Crédits

Ce serveur MCP est basé sur la librairie Python lbc par etienne-hd — un client non-officiel pour l'API Leboncoin. Merci à lui pour le travail de reverse-engineering !

Fonctionnalités

Outil	Description
search_ads	Rechercher des annonces (texte, catégorie, localisation, prix, tri…)
get_ad	Récupérer les détails complets d'une annonce
get_user	Consulter le profil d'un vendeur
list_categories	Lister les catégories disponibles
list_regions	Lister les régions françaises
list_departments	Lister les départements français

📘 Pour des recettes concrètes et des cas d'usage, voir USAGE.md.

Pièges fréquents

Cette section documente les erreurs que les utilisateurs (humains ou IA) font régulièrement avec ce MCP. À lire avant d'appeler search_ads.

1. Le paramètre s'appelle text, pas keywords

// ❌ Ne fait rien, l'API ignore ce champ
{"keywords": "NAS synology"}

// ✅ Correct
{"text": "NAS synology"}

2. Le filtre de livraison s'appelle shippable (bool), pas delivery

// ❌ Ignoré silencieusement
{"delivery": true}

// ✅ Correct
{"shippable": true}

3. sort accepte des valeurs précises

Valeurs valides : NEWEST (défaut), OLDEST, CHEAPEST, EXPENSIVE, RELEVANCE.

// ❌ Ne fait rien
{"sort": "price_asc"}

// ✅ Correct
{"sort": "CHEAPEST"}

4. category attend le nom complet de l'enum

Pas de slash, pas d'accent. Utiliser les valeurs de list_categories : ELECTRONIQUE, VEHICULES, IMMOBILIER, MAISON_ET_JARDIN, MODE, LOISIRS, etc.

Pour filtrer plus finement dans l'électronique : ELECTRONIQUE_ORDINATEURS, ELECTRONIQUE_ACCESSOIRES_INFORMATIQUE, ELECTRONIQUE_PHOTO_AUDIO_ET_VIDEO…

5. region et department veulent des noms d'enum en MAJUSCULES_AVEC_UNDERSCORES

// ❌ Ignoré
{"region": "Île-de-France"}

// ✅ Correct
{"region": "ILE_DE_FRANCE"}

Voir list_regions et list_departments pour la liste exacte.

6. limit est plafonné à 35

Au-delà, le serveur force limit=35 silencieusement. Pour plus de résultats, paginer avec page.

7. Ne pas confondre price_min/price_max (entiers) et price (liste)

Le MCP attend deux entiers séparés. Pas de string, pas de float.

// ❌
{"price": "50-250"}

// ✅
{"price_min": 50, "price_max": 250}

Installation

git clone https://github.com/wydii/leboncoin-mcp.git
cd leboncoin-mcp

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)

python server.py

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

Transport SSE (HTTP)

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) :

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

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 ? »

Pour des appels JSON concrets et testés, voir USAGE.md.

Référence des outils

search_ads

Paramètre	Type	Requis	Description
text	string	non	Texte de recherche (ex. "NAS synology", "vélo électrique"). ⚠️ Ne pas utiliser keywords
url	string	non	URL Leboncoin complète. Si fourni, override text/category/location
category	string	non	Nom d'enum catégorie (voir list_categories). Ex. ELECTRONIQUE_ORDINATEURS
city	string	non	Nom de ville (informatif, utilisé avec latitude/longitude)
latitude	float	non	Latitude pour recherche géographique
longitude	float	non	Longitude pour recherche géographique
radius	int	non	Rayon en mètres (défaut : 30 000 = 30 km)
region	string	non	Enum région en MAJUSCULES (ex. ILE_DE_FRANCE). Voir list_regions
department	string	non	Enum département en MAJUSCULES (ex. GIRONDE). Voir list_departments
price_min	int	non	Prix minimum en euros
price_max	int	non	Prix maximum en euros
sort	string	non	Tri : NEWEST (défaut), OLDEST, CHEAPEST, EXPENSIVE, RELEVANCE
ad_type	string	non	OFFER (défaut) ou DEMAND
owner_type	string	non	PRO, PRIVATE ou ALL
shippable	bool	non	⚠️ Pas delivery. true = articles livrables uniquement
page	int	non	Numéro de page (à partir de 1)
limit	int	non	Résultats par page (max 35, défaut 10)

Retour : dict avec total, total_pro, total_private, max_pages, page, ads[].

get_ad

Paramètre	Type	Requis	Description
ad_id	string	oui	ID numérique de l'annonce (depuis l'URL)

get_user

Paramètre	Type	Requis	Description
user_id	string	oui	ID utilisateur (format UUID)

list_categories / list_regions / list_departments

Aucun paramètre requis.

Dépendances

• lbc >= 1.1.2 — Client Python pour Leboncoin
• FastMCP >= 3.2.0 — Framework pour serveurs MCP en Python

Licence

MIT