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 !

Related MCP server: mcp-lbc

Fonctionnalités

Installation

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)

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

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

Format de réponse

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

leboncoin_get_user

leboncoin_list_categories / leboncoin_list_regions / leboncoin_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