Skip to main content
Glama
Leboncoin MCP Server

Leboncoin MCP Server

Leboncoin MCP Server (France)

Serveur MCP (Model Context Protocol) complet et résilient pour Leboncoin France, conçu pour être connecté à Claude Desktop, Cursor, Cline, Claude Code ou ChatGPT (via Streamable HTTP).

Ce serveur ne se contente pas de chercher des annonces : il intègre un moteur de veille autonome, un suivi d'historique des prix en base SQLite, un collecteur hybride (API + Next.js SSR) pour résister aux protections anti-bot, ainsi qu'une méthodologie experte de recherche et d'audit d'annonces (Skill v4.0.0).


Sommaire


Related MCP server: leboncoin-mcp

🌟 Fonctionnalités clés

  1. Recherche Multi-Critères Avancée :

    • Recherche par mots-clés, filtres de prix min/max, catégories, types de vendeur (particulier/pro), livraison activée.

    • Géolocalisation intelligente : résolution de communes françaises ("Lyon", "69003", "Saint-Denis (974)") avec rayon en km via l'API officielle geo.api.gouv.fr.

    • Réplication directe d'une recherche depuis une URL du site leboncoin.fr.

    • Export en masse (jusqu'à des centaines d'annonces) au format CSV (compatible Excel FR) ou JSON.

  2. Historisation Automatique des Prix :

    • Chaque annonce consultée ou recherchée est enregistrée dans une base de données locale SQLite.

    • Détection des baisses de prix, du prix d'origine et calcul des pourcentages de réduction au fil du temps.

  3. Moteur de Veille en Arrière-Plan (Watchlist) :

    • Possibilité d'enregistrer des recherches récurrentes surveillées par un démon en tâche de fond.

    • Alertes automatiques en cas de nouvelle annonce détectée ou de baisse de prix.

  4. Résilience Anti-Bot Avancée :

    • Collecte hybride : interroge l'API mobile ou bascule de façon transparente sur le rendu web Next.js SSR (__NEXT_DATA__) capable d'extraire les données sans session complexe.

    • Gestion et injection de cookie DataDome (datadome.txt ou variable d'environnement).

    • File d'attente FIFO sérialisée avec temporisation aléatoire pour respecter les limites de débit.

  5. Skill Méthodologique Intégrée (v4.0.0) :

    • Instructions système guidant l'IA pour exclure les annonces déjà vendues ou avec achat en cours (transaction_status), repérer les annonces fantômes (croisement favoris / ancienneté), auditer la réputation du vendeur et calculer le coût complet (prix + port + accessoires).


🛠 Catalogue des Outils MCP

Outil

Description

search_ads

Recherche d'annonces avec filtres complets (texte, URL de recherche, catégorie, ville + rayon, départements, régions, tri, prix min/max, livraison, type de vendeur). Enregistre automatiquement les résultats dans la base SQLite locale pour historiser les prix.

get_ad

Fiche détaillée d'une annonce (titre, prix, description complète, photos HD, statut de transaction, géolocalisation, vendeur et historique de prix enregistré).

get_seller

Profil d'un vendeur (nom, type de compte particulier/pro, note sur 5, nombre d'avis vérifiés, date d'inscription et nombre d'annonces en ligne).

get_price_history

Historique chronologique complet des variations de prix d'une annonce enregistrée dans la base locale (prix initial, prix minimum, baisse en pourcentage).

get_recent_deals

Liste les meilleures baisses de prix récemment observées en base (filtrables par pourcentage minimal de baisse).

add_watchlist

Ajoute une recherche à la veille automatique périodique en arrière-plan.

list_watchlist

Liste toutes les veilles actuellement actives avec leurs paramètres et intervalles de scan.


💡 Prompts et Ressources MCP

En plus des outils, le serveur expose les primitives natives du protocole MCP :

  • Prompt MCP : leboncoin_research

    • Permet à l'IA d'exécuter une recherche guidée en plusieurs passes (termes exacts, synonymes, équivalences d'usage, opportunités récentes) selon la méthodologie d'évaluation v4.0.0.

    • Arguments : besoin, budget_max (optionnel), ville_ou_zone (optionnel).

  • Ressource MCP : leboncoin://skill/research-guide

    • Fournit le texte intégral de la méthodologie d'audit et de qualification d'annonces Leboncoin consultable directement par les agents IA.


🛡 Architecture & Résilience Anti-Bot (DataDome)

Leboncoin est protégé par la solution anti-bot DataDome. Ce serveur intègre plusieurs lignes de défense :

  1. Empreinte TLS / JA3 (via curl_cffi) :

    • Les requêtes HTTP imitent fidèlement les navigateurs modernes (chrome_android ou chrome131) pour éviter le rejet immédiat au niveau handshake TLS.

  2. Collecteur Autonome Next.js SSR :

    • En cas d'inaccessibilité de l'API mobile, le moteur tente d'extraire les données directement depuis le flux Next.js Server-Side Rendering (<script id="__NEXT_DATA__">) de la page web, permettant une récupération propre sans dépendance de jetons applicatifs complexes.

  3. Persistance de session / Cookie DataDome :

    • Si un cookie datadome est requis, le serveur peut le lire automatiquement depuis la variable LBC_DATADOME_COOKIE, un fichier datadome.txt, ou le trousseau local d'un navigateur sur la machine hôte.

  4. File d'attente FIFO & Débit contrôlé :

    • Toutes les requêtes sortantes passent par un verrou sérialisé REQUEST_QUEUE_LOCK avec un délai paramétrable (LBC_MIN_DELAY / LBC_MAX_DELAY) pour éviter tout bannissement d'IP lié aux rafales concurrentes.


📦 Prérequis & Installation

  • Python : Version 3.10 ou supérieure.

  • Système d'exploitation : Linux, macOS ou Windows.

Installation pas à pas

# 1. Cloner le dépôt
git clone https://github.com/votre-compte/MCP-Leboncoin.git
cd MCP-Leboncoin

# 2. Créer l'environnement virtuel Python
python3 -m venv .venv

# 3. Activer l'environnement virtuel
# Sur Linux / macOS :
source .venv/bin/activate
# Sur Windows :
# .venv\Scripts\activate

# 4. Installer les dépendances en mode éditable
pip install --upgrade pip
pip install -e .

🚀 Modes d'Exécution & Configuration

1. Mode local standard : stdio (Claude Desktop / Cursor)

C'est le mode le plus simple pour exécuter le serveur localement sur votre ordinateur personnel.

Configuration pour Claude Desktop

Ouvrez le fichier de configuration de Claude Desktop :

  • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows : %APPDATA%\Claude\claude_desktop_config.json

  • Linux : ~/.config/Claude/claude_desktop_config.json

Ajoutez la section suivante (adaptez le chemin absolu vers votre dossier) :

{
  "mcpServers": {
    "leboncoin": {
      "command": "/chemin/absolu/vers/MCP-Leboncoin/.venv/bin/python",
      "args": ["-m", "lbc_mcp"]
    }
  }
}

Redémarrez ensuite Claude Desktop. Le marteau d'outils Leboncoin apparaîtra dans l'interface.

Configuration pour Claude Code (CLI)

claude mcp add leboncoin -- /chemin/absolu/vers/MCP-Leboncoin/.venv/bin/python -m lbc_mcp

2. Mode serveur HTTP : Streamable HTTP / SSE (ChatGPT / Accès distant)

Pour connecter le serveur à ChatGPT (menu Plugins / Serveurs MCP) ou pour l'exécuter sur une machine distante derrière un reverse-proxy HTTPS (Caddy, Nginx) :

python run_http.py

Par défaut, le serveur écoute sur http://127.0.0.1:8000/mcp.

Exemple de service systemd (Linux)

Pour un fonctionnement permanent en tâche de fond :

[Unit]
Description=Serveur MCP Leboncoin
After=network.target

[Service]
Type=simple
User=votre_utilisateur
WorkingDirectory=/chemin/vers/MCP-Leboncoin
Environment="MCP_HOST=127.0.0.1"
Environment="MCP_PORT=8000"
Environment="MCP_PATH=/mcp"
Environment="MCP_PUBLIC_HOST=localhost"
Environment="ENABLE_MONITOR=0"
ExecStart=/chemin/vers/MCP-Leboncoin/.venv/bin/python /chemin/vers/MCP-Leboncoin/run_http.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

⚙️ Variables d'Environnement

Toutes les variables sont optionnelles et disposent de valeurs par défaut saines :

Variable

Défaut

Description

MCP_HOST

127.0.0.1

Adresse IP d'écoute pour le mode HTTP.

MCP_PORT

8000

Port d'écoute pour le mode HTTP.

MCP_PATH

/mcp

Préfixe du chemin HTTP (ex: /mcp ou /mcp/leboncoin).

MCP_PUBLIC_HOST

localhost

Nom d'hôte public attendu dans les en-têtes HTTP (utile derrière reverse-proxy).

LBC_DB_PATH

~/.local/share/leboncoin/leboncoin.db

Emplacement du fichier de base de données SQLite.

LBC_COOKIE_FILE

~/.config/leboncoin/datadome.txt

Fichier contenant un cookie DataDome valide.

LBC_DATADOME_COOKIE

(aucun)

Valeur directe d'un cookie DataDome valide.

LBC_IMPERSONATE

chrome_android

Empreinte navigateur TLS (chrome_android, chrome131, safari, etc.).

LBC_MIN_DELAY

2.0

Délai minimal aléatoire (en secondes) entre deux requêtes.

LBC_MAX_DELAY

5.0

Délai maximal aléatoire (en secondes) entre deux requêtes.

LBC_PROXY

(aucun)

Proxy HTTP/SOCKS à utiliser (http://user:pass@host:port ou socks5://...).

ENABLE_MONITOR

0

Passer à 1 pour démarrer le démon de veille automatique en arrière-plan.

MONITOR_INTERVAL_SECONDS

300

Intervalle de scrutation de la veille (en secondes).

LBC_EXPORT_DIR

~/Downloads/leboncoin

Dossier par défaut des exports de recherche CSV/JSON.


🧪 Tests & Validation

Lancer la suite de tests unitaires

python -m pytest

(Les tests unitaires utilisent des bouchons et n'émettent pas de requêtes réelles vers Leboncoin).

Lancer le test d'intégration de bout en bout (Smoke Test)

python scripts/smoke_test.py

Ce script démarre le serveur MCP en sous-processus stdio et exécute un cycle de recherche réel pour vérifier l'accès réseau et la validité des parsers.


📚 Bibliothèques & Références

Ce projet s'appuie sur d'excellentes bibliothèques open-source :

  • Model Context Protocol SDK (mcp) : SDK officiel Anthropic pour l'implémentation de serveurs et clients MCP.

  • lbc par @etienne-hd : Client Python non officiel pour l'API Leboncoin.

  • leboncoin-mcp par @BPiroga : Projet initial ayant inspiré cette version améliorée.

  • curl_cffi : Bibliothèque Python avec bindings libcurl et support natif de l'usurpation d'empreinte TLS / JA3 / JA4.

  • geo.api.gouv.fr : API ouverte du gouvernement français pour le géocodage des communes et départements.


⚖️ Licence & Avertissement

  • Ce projet est publié sous Licence MIT.

  • Avertissement légal : Ce logiciel est un projet indépendant et n'a aucun lien d'affiliation avec la société Leboncoin. Il utilise des interfaces non documentées susceptibles d'évoluer. Son utilisation doit être réalisée dans le respect des conditions générales d'utilisation de la plateforme.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      C
      maintenance
      Exposes Leboncoin classified ads to Claude, allowing search with filters and full ad details. Includes rate limiting and optional residential proxy support.
      2
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to search and consult Leboncoin classified ads through the MCP protocol, with tools for ad search, detail retrieval, user profiles, and category/region listings.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search and monitor Dutch and Belgian classifieds (Marktplaats and 2dehands) for listings, seller profiles, and categories.
      8
      75 PyPI
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables turning photos and observed facts into a ready-to-publish Leboncoin ad, with comparable search, asking-price statistics, category lookup, local drafts, and browser form automation that stops one click short of publishing until approved.
      23
      MIT