Documentation

ImmoWP API & intégrations

Serveur MCP

Serveur MCP immobilier : vos annonces dans votre assistant IA

Le serveur MCP d’ImmoWP permet à un assistant IA comme Claude de chercher et de lire les annonces de votre agence, telles que votre logiciel immobilier les transmet à ImmoWP. L’accès est en lecture seule : l’assistant cherche, compare et résume, il ne modifie rien. Le serveur fonctionne pour toute agence dont la passerelle ImmoWP est active, avec la clé d’API de cette agence (la « Clé de licence » de l’extension ImmoWP). Il se branche sur Claude Code, Claude Desktop et d’autres outils compatibles, mais pas sur ChatGPT.

Le serveur MCP est inclus avec la passerelle ImmoWP, sans supplément. Cette page s’adresse à l’agence, qui veut savoir ce qu’elle peut demander à son assistant, et à la personne qui l’installe : agence web, intégrateur ou service informatique.

https://api.immowp.com/mcp?crm=<crm>&client=<client>

Connecter un assistant · Trouver mes paramètres

Qu’est-ce qu’un serveur MCP ?

MCP (Model Context Protocol) est un protocole ouvert qui permet à un assistant IA d’appeler des outils extérieurs pendant une conversation. Un serveur MCP déclare ses outils ; l’assistant choisit celui qui répond à la question posée, l’appelle et lit la réponse. Le serveur MCP d’ImmoWP déclare trois outils, tous en lecture seule, qui donnent accès aux annonces d’une agence.

Ce que l’agence peut demander à son assistant

Les questions se posent en français courant. L’assistant traduit chaque demande en filtres : type d’offre, type de bien, ville ou département, prix, pièces, chambres, surfaces, mots du descriptif.

  • « Quels appartements avons-nous à vendre à Nantes entre 200 000 et 300 000 € ? »
  • « Un acquéreur cherche un T3 avec balcon à Nantes, 280 000 € maximum : que pouvons-nous lui proposer ? »
  • « Liste nos maisons disponibles dans le 44 avec au moins 3 chambres et plus de 500 m² de terrain, les plus grandes d’abord. »
  • « Quelles locations meublées avons-nous à Saint-Nazaire ? »
  • « Montre-moi la fiche complète de la référence VA1234 : prix, honoraires, surfaces, DPE. »
  • « Rédige un texte pour les réseaux sociaux à partir du bien VA1234. »
  • « Quels biens avons-nous vendus ou sous compromis à Guérande ? »
  • « Quand notre site a-t-il importé nos annonces pour la dernière fois, et combien en a-t-il reçu ? »

Sans précision, l’assistant reçoit tous les statuts, vendus compris : demandez les biens disponibles pour ne voir que le stock en vente ou en location.

Comment ça marche

  1. Votre logiciel immobilier transmet vos annonces à ImmoWP, par le même flux que celui qui alimente votre site.
  2. L’API ImmoWP lit ce flux, met les annonces au même format quel que soit le logiciel et garde le résultat en cache une heure.
  3. L’assistant appelle le serveur MCP avec la clé de l’agence. Le serveur interroge l’API ImmoWP, qui rend les annonces de l’agence à laquelle cette clé correspond.

Le serveur MCP ne lit que ce que l’API REST v1 rend pour l’agence, par les routes GET /v1/properties, GET /v1/properties/{id} et GET /v1/status. Il ne lit ni le site WordPress de l’agence, ni les fichiers de contacts ou d’acquéreurs, ni l’agenda du logiciel.

Trouver ses trois paramètres

Le serveur a besoin de trois valeurs, les mêmes que pour l’API v1. Avec l’extension ImmoWP, elles se trouvent dans le WordPress de l’agence, menu Réglages > ImmoWP.

ParamètreOù le trouver (extension ImmoWP)Exemple
crmCode du logiciel, dans l’URL de flux du champ Passerelles de l’onglet Réglages, de la forme https://api.immowp.com/<crm>/<client> ou https://api.immowp.com/?variable1=<crm>&variable2=<client>hektor
clientIdentifiant de l’agence, au même endroitmonagence
clé« Clé de licence » de l’onglet Licence. Elle ne se met jamais dans l’adresse.Confidentielle

Les noms variable1 et variable2, ceux de l’URL de flux, sont acceptés à la place de crm et client. Sur un autre montage, par exemple avec Gestion Immo Pro, ImmoWP vous fournit les trois valeurs sur simple demande.

La clé se transmet toujours dans un en-tête : Key: <clé> ou Authorization: Bearer <clé>. Une clé placée dans l’adresse (paramètre key, api_key ou apikey) est refusée, même si un en-tête valide l’accompagne : elle finirait dans les journaux des serveurs.

Connecter un assistant

Le serveur utilise le transport Streamable HTTP et une clé passée dans un en-tête, sans OAuth. Il fonctionne avec les clients MCP qui permettent d’ajouter un en-tête.

AssistantCompatibleComment
Claude CodeOuiUne commande, avec la clé dans l’en-tête Key.
Claude DesktopOui, par mcp-remoteLe fichier claude_desktop_config.json lance des serveurs locaux : mcp-remote tourne sur le poste et relaie vers ImmoWP avec la clé.
Cursor et autres clients MCP qui acceptent un en-tête personnaliséOuiL’adresse du serveur et l’en-tête Key ou Authorization.
claude.ai et connecteurs personnalisés de Claude DesktopSous conditionSeulement si la section Request headers (bêta, parfois sous Advanced) est disponible, avec l’en-tête Authorization et la valeur Bearer <clé>.
ChatGPTNonSes connecteurs n’acceptent qu’OAuth ou aucune authentification.

Claude Code

claude mcp add --transport http immowp "https://api.immowp.com/mcp?crm=<crm>&client=<client>" --header "Key: <clé>"

Ajoutez --scope user pour rendre le serveur disponible dans tous vos projets. N’utilisez pas --scope project : la clé serait écrite dans le fichier .mcp.json du projet, souvent versionné. La clé est enregistrée en clair dans la configuration de Claude Code (~/.claude.json).

Claude Desktop

Claude Desktop se branche par mcp-remote, un outil open source (licence MIT) lancé par npx, qui demande Node.js 18 ou plus sur le poste. Le fichier claude_desktop_config.json lance des serveurs locaux : mcp-remote y joue le rôle de serveur local qui relaie vers ImmoWP avec la clé. Un serveur distant peut aussi s’ajouter comme connecteur personnalisé, mais il suit alors la même bêta que claude.ai (voir plus bas). Ajoutez l’entrée immowp dans la section mcpServers de ~/Library/Application Support/Claude/claude_desktop_config.json sous macOS, ou de %APPDATA%\Claude\claude_desktop_config.json sous Windows, sans effacer les serveurs déjà déclarés.

{
  "mcpServers": {
    "immowp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.immowp.com/mcp?crm=<crm>&client=<client>",
        "--header",
        "Key:${IMMOWP_KEY}"
      ],
      "env": {
        "IMMOWP_KEY": "<clé>"
      }
    }
  }
}

Ne mettez pas d’espace après Key: dans args : sous Windows, Claude Desktop casse les arguments qui contiennent une espace. mcp-remote remplace lui-même ${IMMOWP_KEY} par la valeur indiquée dans env. La clé reste en clair dans ce fichier. Pour la garder hors de la liste des processus, mcp-remote accepte aussi l’option --header-file, suivie du chemin d’un fichier qui contient la ligne Key: <clé>. Redémarrez Claude Desktop après la modification.

Cursor

Ajoutez l’entrée immowp dans la section mcpServers de ~/.cursor/mcp.json (tous les projets) ou de .cursor/mcp.json (un projet). La clé est lue dans la variable d’environnement IMMOWP_KEY, à définir dans votre profil de shell ou dans les variables d’environnement du système, puis redémarrez Cursor.

{
  "mcpServers": {
    "immowp": {
      "url": "https://api.immowp.com/mcp?crm=<crm>&client=<client>",
      "headers": {
        "Authorization": "Bearer ${env:IMMOWP_KEY}"
      }
    }
  }
}

Source : documentation MCP de Cursor.

claude.ai (connecteur personnalisé)

Dans claude.ai, comme pour un connecteur personnalisé de Claude Desktop, la connexion part des serveurs d’Anthropic, et une clé ne peut être transmise que dans la section Request headers de la fenêtre d’ajout du connecteur. Anthropic indique que cette section est en bêta et réservée à une partie des organisations ; quand la fenêtre présente tous les réglages sur un même écran, elle se trouve sous Advanced. Si elle est disponible, choisissez No sign-in, l’en-tête authorization (le nom Key est refusé) et la valeur Bearer suivie d’une espace et de la clé, comme l’explique la documentation d’Anthropic ; dans une organisation, la clé enregistrée est partagée par tous ses membres. Si la section n’apparaît pas, votre organisation n’a pas accès à cette bêta : utilisez Claude Code, ou Claude Desktop avec mcp-remote.

ChatGPT

ChatGPT ne peut pas utiliser le serveur MCP d’ImmoWP. Ses connecteurs n’acceptent qu’OAuth ou l’absence d’authentification, et la documentation d’OpenAI précise que ChatGPT ne sait pas présenter une clé d’API personnalisée. Or le serveur ImmoWP exige la clé de l’agence dans un en-tête. Utilisez Claude Code, Claude Desktop ou un autre client compatible.

Autre client MCP

Un client MCP convient s’il gère le transport Streamable HTTP et les en-têtes personnalisés, et s’il prend en charge l’une des versions du protocole acceptées (voir Limites) ou sait y revenir : adresse https://api.immowp.com/mcp?crm=<crm>&client=<client>, avec l’en-tête Key: <clé> ou Authorization: Bearer <clé>. Avec le SDK MCP TypeScript, le délai par défaut de 60 secondes suffit : il dépasse la durée maximale d’une requête.

Vérifier la connexion

L’état Connected affiché par claude mcp list ou /mcp indique seulement que l’adresse répond : l’initialisation et la liste des outils ne demandent pas de clé. Pour vérifier la clé et les paramètres crm et client, demandez à l’assistant « Appelle get_sync_status », ou lancez cette commande dans un terminal macOS ou Linux :

curl -s "https://api.immowp.com/mcp?crm=<crm>&client=<client>" \
  -H "Key: <clé>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_sync_status","arguments":{}}}'

Si l’une des trois valeurs est fausse, l’appel rend une erreur qui dit quoi vérifier, et l’assistant peut l’expliquer. Une recherche prend la même forme, avec "name":"search_properties","arguments":{"city":"Nantes","offer_type":"sale","status":"available","per_page":5}.

Les trois outils

Les trois outils sont en lecture seule (annotation readOnlyHint) et décrits en anglais pour l’assistant.

OutilRôleParamètres
search_propertiesCherche dans le catalogue de l’agence.Filtres facultatifs et cumulables, détaillés ci-dessous.
get_propertyRend la fiche complète normalisée d’une annonce : descriptions, prix et honoraires, surfaces, pièces, DPE et GES, localisation, photos, agence et négociateur.id (prioritaire) ou reference
get_sync_statusRend l’état de la passerelle (connecteur, passerelle active) et le dernier import déclaré par le site de l’agence (résultat, nombre d’annonces, date).Aucun

Filtres de search_properties

  • offer_type : sale, rent, seasonal_rent, life_annuity, program.
  • property_type : apartment, house, land, parking, commercial, office, building, program, warehouse.
  • status : available, sold (compromis et offres compris), rented, off_market.
  • city : nom de ville, sans tenir compte de la casse ni des accents, ou début de code postal de 2 à 5 chiffres (44 couvre la Loire-Atlantique), ou les deux (Nantes 44000) ; plusieurs villes séparées par des virgules.
  • min_price et max_price : prix de vente, ou pour une location le loyer charges comprises quand il est connu.
  • min_rooms, min_bedrooms, min_surface (surface habitable) et min_land_surface (terrain), en m².
  • query : mots cherchés dans le titre, la description et la référence.
  • sort : price_asc, price_desc, surface_desc, recent.
  • page et per_page : 20 annonces par page par défaut, 50 au plus.

Pour chaque annonce, search_properties rend un résumé : id, reference, title, offer_type, property_type, status, price, currency, rent_period, charges_included, city, postal_code, living_area_sqm, land_area_sqm, rooms, bedrooms et photo_url. Le résultat donne aussi total, page, per_page, pages et catalogue_total. Le détail des champs d’une fiche figure dans le modèle de données.

Logiciels compatibles : Hektor, Apimo, Netty et les autres

Le serveur MCP lit ce que lit l’API ImmoWP. Il fonctionne donc pour toute agence dont la passerelle ImmoWP est active, quel que soit son logiciel, notamment :

La configuration ne change pas d’un logiciel à l’autre : crm et client sont ceux de l’URL de flux de l’agence. Les champs disponibles dépendent de ce que le logiciel transmet dans son flux. La liste complète des logiciels figure sur la page Passerelles.

Sécurité et données

  • Lecture seule : aucun outil n’écrit. L’assistant ne peut ni créer, ni modifier, ni supprimer une annonce, ni dans le logiciel ni sur le site.
  • Une clé, une agence : la clé d’une agence n’ouvre que le catalogue de cette agence. L’API vérifie à chaque appel que la clé correspond aux paramètres crm et client.
  • La clé voyage dans un en-tête, sur une connexion HTTPS, jamais dans l’adresse.
  • La clé est enregistrée en clair dans la configuration du client IA (~/.claude.json pour Claude Code, claude_desktop_config.json pour Claude Desktop) : réservez ces configurations aux postes et aux comptes de l’agence. Dans un connecteur claude.ai, c’est Anthropic qui conserve la clé, partagée par tous les membres de l’organisation.
  • La fiche complète rendue par get_property comprend l’adresse et les coordonnées GPS du bien, même si l’adresse est masquée sur le site, ainsi que les coordonnées du négociateur. Le prix est rendu même s’il est masqué sur le site, par search_properties comme par get_property.
  • Les réponses passent par le fournisseur de l’assistant (Anthropic pour Claude, par exemple), selon ses propres conditions.
  • Pour couper l’accès d’un assistant, retirez le serveur de sa configuration. En cas de clé exposée, contactez ImmoWP.

Limites

  • Fraîcheur : les annonces sont lues dans le flux du logiciel. En temps normal, une modification publiée dans ce flux apparaît avec au plus une heure de décalage, dû au cache de l’API.
  • Dernier import : get_sync_status rend le dernier import déclaré par le site WordPress. Un import absent ou ancien ne veut pas dire que le catalogue est vide, puisque la recherche lit le flux directement.
  • Volume et délais : chaque recherche relit tout le catalogue de l’agence, dans la limite de 50 secondes par requête et de 25 secondes par appel à l’API. Aucun volume de catalogue n’est garanti.
  • Locations saisonnières : quand le flux ne donne pas la période du loyer, ce qui arrive notamment avec Netty et Ubiflow, une location saisonnière reste classée en location ordinaire.
  • Charge : au plus trois requêtes d’outil interrogent l’API en même temps, toutes agences confondues. Au-delà, une requête attend une place pendant trois secondes au plus, puis rend le message « The ImmoWP MCP server is busy » : il suffit de reposer la question.
  • Protocole : transport Streamable HTTP sans état, avec des réponses JSON, sans flux SSE ni session. Versions acceptées : 2025-06-18, 2025-03-26 et 2024-11-05.

Questions fréquentes

Le serveur MCP est-il payant ?

Non. Le serveur MCP est inclus avec la passerelle ImmoWP, sans supplément. Il fonctionne avec la clé d’API de la passerelle de l’agence, tant que cette passerelle est active. Le compte de l’assistant, Claude ou un autre, reste à ouvrir auprès de son éditeur.

Faut-il un développeur pour connecter le serveur MCP ?

Non, mais il faut savoir coller une commande ou modifier un fichier de configuration. Dans Claude Code, le serveur s’ajoute en une commande. Claude Desktop demande un bloc de configuration et Node.js sur le poste. La personne qui gère votre site ou votre informatique peut s’en charger.

Le serveur MCP fonctionne-t-il avec Hektor, Apimo ou Netty ?

Oui. Le serveur lit les annonces que l’API ImmoWP reçoit du logiciel de l’agence. Il fonctionne avec Hektor, Apimo, Netty (devenu Modelo Office) et tout autre logiciel relié à ImmoWP, dès lors que la passerelle de l’agence est active.

L’assistant peut-il modifier ou supprimer mes annonces ?

Non. Les trois outils du serveur sont en lecture seule. Les annonces se modifient toujours dans votre logiciel immobilier.

Une autre agence peut-elle voir mes annonces ?

Non. La clé d’une agence n’ouvre que le catalogue de cette agence : à chaque appel, l’API ImmoWP vérifie que la clé correspond aux paramètres crm et client.

Peut-on utiliser le serveur MCP dans ChatGPT ?

Non. Les connecteurs de ChatGPT n’acceptent qu’une connexion par compte (OAuth) ou aucune authentification : ils ne savent pas transmettre la clé de l’agence, que le serveur ImmoWP exige.

Peut-on utiliser le serveur MCP dans claude.ai ?

Seulement si la fenêtre d’ajout d’un connecteur personnalisé propose la section Request headers, en bêta pour une partie des organisations et parfois rangée sous Advanced. Sinon, utilisez Claude Code, ou Claude Desktop avec mcp-remote.

Les annonces sont-elles à jour ?

Le serveur lit les annonces dans le flux que votre logiciel publie pour ImmoWP, pas dans votre site WordPress. En temps normal, une modification publiée dans ce flux apparaît avec au plus une heure de décalage, dû au cache de l’API. Le rythme de publication du flux dépend de votre logiciel.

Quelle différence avec l’API ImmoWP ?

L’API v1 sert les sites et les développeurs. Le serveur MCP est un adaptateur au-dessus de cette API : il appelle les mêmes routes, avec la même clé, et les présente sous forme d’outils qu’un assistant sait utiliser.

Pour aller plus loin