mcp-immo-olv

Données immobilières françaises issues de l'open data public À partir d'une adresse, un client MCP peut consulter les ventes notariées (DVF), obtenir une estimation par comparables, les loyers d'annonce, une indication de la taxe foncière, les DPE, les risques Géorisques et le profil INSEE de la commune — sans clé API..

L'objet de ce MCP, produire des données à partir de sources fiables

Les portails immobiliers affichent parfois des prix demandés et des estimations opaques. Les données publiques françaises offrent mieux : actes notariés DVF, diagnostics ADEME, indicateurs de loyer, fiscalité locale REI, risques et référentiels d'adresses. mcp-immo-olv les relie dans des réponses auditables.

Chaque chiffre expose sa source, sa portée et ses limites. Une estimation reste une analyse d'open data, pas un avis de valeur professionnel ni un conseil financier.

Modalités de connexion

Prérequis unique : Node.js 18 ou plus récent. Aucune clé API, aucun compte. Par défaut le serveur tourne en local, en stdio : rien n'est exposé sur le réseau. Un mode Streamable HTTP optionnel (variable IMMO_HTTP_PORT) permet de l'héberger et de le partager — voir § 6.

1. Claude Code

claude mcp add immo-olv -- npx -y mcp-immo-olv@latest

Vérifier avec claude mcp list : immo-olv doit y figurer. Pour les commandes /immo-olv:rapport, /immo-olv:estimation et /immo-olv:risques, installez le plugin (voir Installer en plugin Claude Code).

2. Cline

En une commande (CLI cline) :

cline mcp add immo-olv --yes -- npx -y mcp-immo-olv@latest

Sans --yes, la commande ouvre l'assistant d'ajout avec ces champs pré-remplis. Vérifier avec cline config mcp : immo-olv doit y figurer, actif.

Depuis l'IDE : dans le panneau Cline, icône MCP Servers (barre d'outils) → onglet Configure → bouton Configure MCP Servers, puis ajouter dans mcpServers :

{
  "mcpServers": {
    "immo-olv": {
      "command": "npx",
      "args": ["-y", "mcp-immo-olv@latest"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

L'extension ouvre son propre fichier de réglages MCP ; la CLI, elle, lit ~/.cline/data/settings/cline_mcp_settings.json (surcharge possible avec la variable CLINE_MCP_SETTINGS_PATH). Ensuite, redémarrer Cline : les 21 outils apparaissent dans la liste MCP.

3. Tout autre client MCP

Copier ce bloc dans la configuration du client (mcpServers) :

{
  "mcpServers": {
    "immo-olv": {
      "command": "npx",
      "args": ["-y", "mcp-immo-olv"]
    }
  }
}

Redémarrer le client : les 21 outils apparaissent dans sa liste d'outils MCP.

4. Depuis ce dépôt (développement)

npm install
npm run build

Pointer ensuite le client sur le build local au lieu du paquet publié :

{
  "mcpServers": {
    "immo-olv": {
      "command": "node",
      "args": ["/chemin/vers/mcp-immo-olv/dist/index.js"]
    }
  }
}

Équivalent en une commande avec Claude Code :

claude mcp add immo-olv -- node /chemin/vers/mcp-immo-olv/dist/index.js

Le serveur se lance aussi seul, mais il attend un client sur stdin :

node dist/index.js

5. Console web (sans client MCP)

npm --prefix ui install
npm run build        # le pont a besoin de dist/index.js
npm run dev          # console : http://localhost:5173

Sans rien installer, un client compatible résout le serveur depuis le registre MCP officiel sous le nom io.github.OlivierLAVAUD/mcp-immo — voir Installer depuis le registre MCP.

6. Hébergement / Streamable HTTP

Par défaut le serveur est un processus stdio lancé par un client MCP. En définissant IMMO_HTTP_PORT, ce même registre d'outils bascule sur le transport MCP Streamable HTTP, pour l'héberger, le partager en équipe ou le joindre depuis un client qui ne sait pas lancer un sous-processus.

IMMO_HTTP_PORT=8123 npx -y mcp-immo-olv@latest
# → mcp-immo-olv listening on Streamable HTTP: http://127.0.0.1:8123/mcp

Point un client MCP « remote » sur l'URL de l'endpoint :

{
  "mcpServers": {
    "immo-olv": { "url": "http://127.0.0.1:8123/mcp" }
  }
}

À savoir avant d'exposer le serveur :

• Bouclage local par défaut. Il n'écoute que sur 127.0.0.1 : un serveur MCP sans authentification donne accès à tout le surface d'outils. Pour le partager au-delà de la machine, liez-le délibérément (IMMO_HTTP_HOST) et protégez l'accès (reverse proxy avec authentification, pare-feu…). Aucune authentification n'est implémentée côté serveur.
• Sessions. Chaque session MCP (initialize) reçoit son propre couple serveur/transport, routé par l'en-tête Mcp-Session-Id. Une session inconnue répond 404, une méthode non autorisée 405.
• Réponses JSON. Chaque outil est une requête/réponse unique (pas de flux serveur-initié), donc le serveur répond en JSON direct — compatible curl et tout client Streamable HTTP (qui doit accepter application/json et text/event-stream, comme le veut la spécification).
• stdio reste la voie par défaut. Rien ne change pour Claude Code, Cline ou tout client qui lance le paquet : sans IMMO_HTTP_PORT, c'est exactement le même comportement qu'avant.

Installer depuis le registre MCP

Le serveur est référencé dans le registre officiel MCP sous le nom :

io.github.OlivierLAVAUD/mcp-immo

Un client capable de résoudre un serveur depuis le registre le trouve par ce nom, sans clé API ni compte à créer. Le registre ne stocke que les métadonnées : le serveur tourne en local, en stdio, et se lance depuis le paquet npm mcp-immo-olv. La configuration manuelle ci-dessus reste équivalente.

# Vérifier la fiche publiée
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.OlivierLAVAUD%2Fmcp-immo"

Installer en plugin Claude Code

Le dépôt est aussi un marketplace de plugins Claude Code. Deux commandes suffisent, sans clé API :

claude plugin marketplace add OlivierLAVAUD/mcp-immo-olv
claude plugin install immo-olv@mcp-immo-olv

Le plugin immo-olv lance le serveur MCP en stdio via npx -y mcp-immo-olv@latest, et ajoute trois commandes qui pré-câblent les appels d'outils :

Un skill de cadrage (immobilier-france) accompagne les outils : il impose de citer la source de chaque chiffre, de ne jamais inventer une donnée, et de traiter un risque available: false comme inconnu et non comme absent.

Sous Windows natif, si npx n'est pas résolu, déclare le serveur à la main :

claude mcp add immo-olv -- cmd /c npx -y mcp-immo-olv@latest

Outils

Sortie structurée

Les 21 outils déclarent le schéma de leur résultat (outputSchema, spécification MCP 2025-06-18). Chaque appel renvoie donc la même charge utile deux fois : structuredContent, l'objet validé par le SDK avant envoi, et le bloc texte JSON historique, conservé pour les clients antérieurs à cette révision. Un client peut typer le résultat, le rendre sans le reparser, et faire confiance à la forme annoncée — estimate_property promet estimate.per_m2.estimate, estimate.confidence, estimate.top_comps[], et le serveur échoue plutôt que de livrer autre chose.

Les schémas sont volontairement ouverts (additionalProperties: true) : un champ ajouté par une source en amont ne peut pas invalider un outil. Ils sont vérifiés à deux niveaux — test/output-schemas.test.ts les confronte à un payload réel capturé (ui/fixtures/property-report-lyon.json), et npm run smoke valide les réponses live contre les mêmes schémas.

Taxe foncière et rendement « net »

property_tax_estimate ne prétend jamais connaître l'avis de taxe foncière d'un bien. Le REI publie des montants agrégés et nombres d'articles imposés par commune : le serveur calcule leur charge moyenne, avec les composantes publiées (part communale, intercommunale, syndicats, GEMAPI, TEOM). L'avis réel dépend de la valeur locative cadastrale, des exonérations, du propriétaire et de l'imposition : demandez-le avant tout achat.

Le rendement après taxe moyenne retire cette seule moyenne au loyer annuel. Il ne déduit ni charges de copropriété, assurance, gestion, vacance, travaux ni impôt sur les revenus : ce n'est pas un rendement net-net.

Exemples

Les sorties réelles des outils — digest de risques, proximité, comparaison, recherche par budget, fiche Markdown, lots d'adresses et messages d'erreur — sont dans EXAMPLES.md, rejouables avec npm run examples.

Des prompts d'exemple pour les 21 outils (à copier dans votre client), classés par besoin et par parcours, sont dans Prompts.md. Ils incluent des prompts qui vérifient les garde-fous : source injoignable → inconnu, estimation refusée sous trois comparables, adresse inexistante.

Méthodologie d'estimation

L'estimation est une médiane pondérée des ventes comparables : même type de bien, surface 40–250 % de la cible, un seul logement par acte, valeurs extrêmes écartées. Les prix anciens sont ramenés au niveau du dernier millésime de marché par commune (coefficient borné 0,7–1,6). Les poids combinent distance, similarité de surface et ancienneté ; les quartiles pondérés donnent la fourchette. Chaque comparable, son ajustement et son poids sont restitués.

Le moteur refuse une estimation sous trois comparables. Il ne connaît ni l'état, ni l'étage, ni la vue, ni les travaux, ni les contraintes juridiques.

Backtesting du moteur

backtest_estimator rejoue le moteur sur les ventes de la commune : chaque vente est estimée en n'utilisant que les ventes enregistrées avant sa propre date (découpe asOf, acte exclu), puis comparée au prix réellement payé. Aucun comparable futur, aucun niveau de marché futur ne peut fuiter.

Il publie la MAPE, l'erreur médiane et le 90ᵉ centile, le biais signé (positif = le modèle surestime) et la couverture de l'intervalle P25–P75 — à lire près de 50 %, pas 95 % : un intervalle P25–P75 bien calibré contient la moitié des ventes réalisées. Le tout est ventilé par bande de surface et par année, avec les dix plus grosses erreurs pour audit. Une exécution de contrôle sur Lyon donne une MAPE d'environ 21 %, un biais de +8 % et une couverture de 52,5 %.

Sources, licences et limites

Chaque jeu renvoie à sa page de référence officielle (le nom du jeu est un lien) ; les URL que le serveur renvoie dans une réponse — source_url, officialReportUrl, unavailable.portal_url — sont vérifiées en direct par npm run smoke.

Licences : Licence Ouverte / Open Licence (Etalab) pour les jeux de l'État cités ici, ODbL pour OpenStreetMap ; certains jeux de collectivités ont leur propre licence, à vérifier sur la fiche du jeu avant réutilisation. La source doit être citée dès qu'une réponse est reprise. Les jeux publics sont interrogés en direct, sans clé API. Le cache mémoire réduit la latence et les appels répétés, mais est vidé au redémarrage ; définir IMMO_CACHE_DIR (un dossier inscriptible) persiste les lignes DVF lues sur disque — un redémarrage réhydrate depuis le fichier au lieu de tout re-télécharger, sans changer les données servies.

Développement

npm install
npm run build
npm test          # tests unitaires, sans réseau
npm run smoke     # vérification live des API publiques
npm run examples  # exemples live, commentés dans EXAMPLES.md

cd ui
npm install
npm run dev       # console avec hot reload : http://localhost:5173
npm run build
npm start         # console compilée + pont MCP : http://localhost:8787
npm run smoke     # test de rendu avec fixtures réelles

Depuis la racine, les mêmes commandes sont accessibles sans changer de dossier (npm run dev délègue à ui/) :

npm --prefix ui install
npm run dev       # console avec hot reload
npm run ui:build  # compile l'interface
npm run ui:start  # console compilée + pont MCP sur un seul port

Licence

MIT. Copyright © 2026 Olivier LAVAUD (voir LICENSE).