SSD Nodes Learn Hosting plans →
Guides Matt ConnorPar Matt Connor

Connecter Claude à Home Assistant avec MCP derrière sa box

Intégration officielle ou ha-mcp, accès distant derrière une Freebox ou une Livebox, puis un réglage étroit : compte dédié, lecture seule et entités exposées seulement.

Deux façons de connecter Claude à Home Assistant avec MCP

Pour connecter Claude à Home Assistant avec MCP (Model Context Protocol, le protocole qui permet à un assistant d'appeler des outils), utilisez l'intégration officielle de Home Assistant. Elle existe depuis Home Assistant 2025.2. Elle gère la connexion par OAuth et elle sait limiter ce que Claude voit. Le serveur communautaire ha-mcp ne sert que si vous avez besoin d'un outil précis qu'elle n'offre pas.

Avec claude.ai ou Claude Desktop, Claude doit pouvoir joindre votre Home Assistant depuis Internet. Derrière une Freebox ou une Livebox, c'est là que se trouve le vrai travail : choisir un accès distant, puis réduire ce que Claude a le droit de faire chez vous.

  • Voie 1, l'intégration MCP Server de Home Assistant. Point d'entrée /api/mcp. Rien d'autre à installer. C'est le bon choix pour presque tout le monde.
  • Voie 2, ha-mcp. Projet communautaire sous licence MIT. La dernière version stable est la v9.2.0, publiée le 11 novembre 2026. Il apporte plus d'outils, donc une plus grande surface d'attaque, et il change très souvent.

Ce que l'intégration officielle expose par défaut

L'intégration range ses outils en ensembles (les « tool sets »). Deux ensembles comptent ici :

  • Home Assistant : il lit toutes les entités, les journaux et l'historique, et il peut lancer n'importe quelle action. Il exige un compte administrateur.
  • Device control : il donne à Claude les mêmes outils que l'assistant vocal Assist. Il ne voit et ne contrôle que les entités exposées aux assistants vocaux.

L'intégration publie plusieurs adresses. L'URL principale, /api/mcp, suit les options de l'intégration. Chaque ensemble a aussi sa propre URL, par exemple /api/mcp/assist, qui n'expose que Device control. Ces URL individuelles ignorent les options de l'URL principale et ne sont jamais en lecture seule. Toutes, sauf celle de Device control, exigent un compte administrateur.

Voici les options de l'URL principale et leur valeur à l'installation, d'après la page de l'intégration lue le 13 novembre 2026 :

  • « Expose all AI tools » est activée. Tous les ensembles sont exposés, y compris ceux qu'une intégration ajoutera plus tard.
  • « Require an administrator account » est activée.
  • « Read-only » est désactivée. Une fois activée, elle limite l'URL principale aux outils qui ne modifient rien.

Avec ces valeurs, l'ensemble Home Assistant est exposé. Claude, connecté avec un compte administrateur, peut donc lire tout l'historique de la maison et lancer n'importe quelle action. Attention à un piège : si vous aviez installé l'intégration avant l'arrivée de ces options, « Expose all AI tools » et « Require an administrator account » restent désactivées après la mise à jour. Ouvrez les options de l'intégration et regardez ce qui est réellement coché chez vous.

Ce que la page de Home Assistant dit de Claude

La section Claude de la page de l'intégration dit ceci (lue le 13 novembre 2026) :

Claude connects to your MCP server from the cloud, also when you use Claude Desktop. Your Home Assistant instance must be accessible from the internet.

Autrement dit, la connexion ne part pas de votre ordinateur. Elle part des serveurs d'Anthropic, même quand vous utilisez l'application Claude Desktop. Le centre d'aide de Claude le confirme : un connecteur personnalisé doit être joignable depuis Internet, à partir des plages d'adresses IP d'Anthropic. Un serveur sur un réseau privé, derrière un VPN ou bloqué par un pare-feu ne se connecte pas, sauf si vous autorisez les adresses d'Anthropic. Une adresse comme 192.168.1.50, ou une adresse visible seulement dans votre tailnet, ne marche donc ni avec claude.ai ni avec Claude Desktop. Le connecteur distant doit aussi être joignable sur le port HTTPS standard 443 : Claude refuse les URL qui indiquent un autre port. Les serveurs locaux configurés dans Claude Desktop via claude_desktop_config.json utilisent, eux, votre réseau local.

Côté abonnement, les connecteurs personnalisés existent sur les offres Free, Pro, Max, Ultra, Team et Enterprise. L'offre Free est limitée à un seul connecteur personnalisé. Sur Pro et Max, le chemin est Customize > Connectors > + Add > Add custom connector. Sur Team et Enterprise, seuls les propriétaires (et certains rôles Enterprise) ajoutent des connecteurs, dans Organization settings > Connectors.

Et Claude Code sur le réseau local ?

Claude Code tourne dans votre terminal. On pourrait donc penser qu'il joint directement http://homeassistant.local:8123. Voici ce que disent les deux documentations.

La page de Home Assistant écrit : « Claude Code connects to MCP servers over HTTPS only. » Elle demande aussi d'utiliser l'URL de votre instance accessible à distance. Elle ne prévoit pas d'exception pour un Claude Code installé sur le réseau local.

La documentation MCP de Claude Code ne dit pas d'où partent les connexions HTTP. Elle ne pose pas non plus de règle générale qui imposerait HTTPS. Elle fixe en revanche une règle pour la connexion OAuth, décrite pour le runtime v2 (celui qui repose sur MCP TypeScript SDK 2.0) : les identifiants OAuth ne partent que vers un point de jeton servi en HTTPS, ou situé sur localhost, 127.0.0.1 ou ::1. Elle ajoute : « Sign-in fails for a server whose token endpoint is plain http:// anywhere else, such as a device on your local network. »

Conclusion pratique. Avec une URL en http:// sur le réseau local, la connexion OAuth échoue, au moins sur le runtime v2. Avec une URL HTTPS visible seulement chez vous, par exemple via Tailscale Serve, aucune des deux documentations ne confirme ni n'exclut que cela marche. Nous ne l'avons pas testé. Traitez-le comme une expérience, pas comme une méthode.

Les commandes de la page de Home Assistant sont les suivantes. Remplacez l'URL par la vôtre :

claude mcp add --transport http home-assistant https://ha.example.fr/api/mcp
claude mcp login home-assistant

claude mcp login lance la connexion OAuth depuis le shell. Le navigateur s'ouvre sur la page de connexion de Home Assistant. Connectez-vous avec le compte que Claude doit utiliser, pas avec le vôtre (voir plus bas). Dans une session, la commande /mcp affiche l'état du serveur. Pour effacer les identifiants plus tard, lancez claude mcp logout home-assistant.

La portée par défaut de claude mcp add est « local » : le serveur ne se charge que dans le projet où vous l'avez ajouté, et sa configuration reste privée dans ~/.claude.json. C'est ce qu'il vous faut. Ne mettez pas ce serveur dans un fichier .mcp.json partagé dans un dépôt git.

Rendre Home Assistant joignable derrière une Freebox ou une Livebox

Les exemples ci-dessous utilisent le port 8123. Depuis Home Assistant 2026.8, le port par défaut est 80 sur Home Assistant OS et reste 8123 sur Home Assistant Container. Adaptez les commandes au port configuré chez vous.

Deux règles de Home Assistant valent pour toutes les options qui passent par un proxy ou un tunnel.

  • Le proxy doit être déclaré. Home Assistant bloque les requêtes qui arrivent par un reverse proxy qu'il ne connaît pas. Déclarez-le dans Paramètres > Système > Réseau (« Trust X-Forwarded-For » et la liste des proxies de confiance).
  • L'URL doit correspondre. Pour que OAuth fonctionne, l'URL que vous donnez à Claude doit être celle configurée comme URL interne ou externe dans Paramètres > Système > Réseau. Sinon la connexion échoue.

La documentation de Home Assistant sur l'accès distant contient une phrase à garder en tête : « Just putting a port up is not secure. » Pour chaque option ci-dessous, la vraie question est donc : qu'est-ce qui devient public, et contre quoi êtes-vous protégé ?

Freebox : redirection de port ou IPv4 full-stack

Avec une redirection de port, votre page de connexion Home Assistant devient publique sur l'adresse IP de votre box. C'est à vous de fournir le TLS (transport layer security, le chiffrement de HTTPS). La seule barrière est l'authentification de Home Assistant. Vous êtes protégé par la qualité de vos mots de passe et par vos mises à jour, et par rien d'autre.

Sur une ligne Free dont l'IPv4 est partagée entre plusieurs abonnés, tous les ports ne sont pas forcément à vous. Regardez donc l'état de la connexion Internet dans Freebox OS avant de choisir un port. L'aide de Free documente en revanche l'IPv4 fixe « full-stack » : elle donne accès à tous les ports de l'adresse attribuée. Elle se demande dans l'Espace Abonné, rubrique « Ma Freebox », lien « Demandez une adresse IP V4 fixe full-stack ». Il faut la redemander après un déménagement, et la confirmation demande de redémarrer le Freebox Server 30 minutes plus tard.

Livebox

Orange documente la création de règles NAT/PAT sur la Livebox 5 : attribuez une IP fixe à l'équipement, puis ouvrez Paramètres avancés > Réseau > NAT/PAT dans l'interface de la box. Regardez les réglages réseau de votre propre Livebox et posez la question à Orange avant de compter sur une redirection de port. Si elle n'est pas possible, les options suivantes ne demandent aucun port ouvert sur la box.

Nabu Casa annonce que Home Assistant Cloud deviendra Home Assistant Link le 2 décembre 2026. Le 15 novembre 2026, sa page de tarifs affichait 7,50 EUR par mois ou 75,00 EUR par an, hors taxes, avec un essai gratuit de 31 jours sans carte bancaire. Vérifiez le prix dans votre devise au moment de payer. L'accès distant est inclus et ne demande aucun port ouvert sur la box.

Ce qui devient public : votre Home Assistant, à l'adresse fournie par Nabu Casa. Ce qui est protégé : votre box n'ouvre aucun port, et vous n'avez ni certificat ni proxy à gérer. La page de l'intégration MCP le recommande d'ailleurs en cas de problème OAuth, car Home Assistant Cloud « avoids reverse-proxy and tunnel configuration pitfalls ». C'est l'option la plus simple derrière une box française.

Tailscale Funnel

Tailscale Serve partage un service uniquement dans votre tailnet. Claude, qui se connecte depuis le cloud, ne peut donc pas le joindre. Funnel est la version publique : il ouvre le service à tout Internet, y compris aux personnes qui n'utilisent pas Tailscale. Le choix entre les deux est détaillé dans notre comparaison de Tailscale Serve et Tailscale Funnel.

Au 13 novembre 2026, Funnel est en bêta et disponible sur toutes les offres Tailscale. Il demande Tailscale v1.38.3 ou plus récent, MagicDNS, HTTPS activé et un attribut funnel dans la politique du tailnet. Il n'écoute que sur les ports 443, 8443 et 10000, en TLS uniquement, avec des limites de débit que vous ne pouvez pas régler. Sur la machine qui fait tourner Home Assistant, la commande suit l'exemple de la documentation (tailscale funnel 3000), avec le port de Home Assistant :

sudo tailscale funnel 8123

Ce qui devient public : tout ce qui est servi sur ce port, donc toute l'interface de Home Assistant et pas seulement /api/mcp. Funnel n'authentifie pas les visiteurs. La connexion de Home Assistant est la seule barrière. Ce qui est protégé : les relais de Tailscale ne déchiffrent pas le trafic, et l'adresse IP de votre box reste cachée.

Cloudflare Tunnel

Le démon cloudflared ouvre uniquement des connexions sortantes vers le réseau de Cloudflare. Vous pouvez donc bloquer tout le trafic entrant sur la box, et vous n'avez pas besoin d'adresse IP publique. Ce qui devient public : le nom d'hôte que vous publiez, et derrière lui Home Assistant. Ce nom est un CNAME vers <UUID>.cfargotunnel.com, pas vers votre adresse. Ce qui est protégé : aucun port n'est ouvert chez vous. Pensez à déclarer le tunnel comme proxy de confiance dans Home Assistant.

Tunnel inverse vers un VPS

Une IPv4 publique n'est pas garantie avec un VPS : cela dépend du fournisseur et de la configuration. Pour cette méthode, choisissez un VPS avec une IPv4 publique. Un tunnel SSH inverse, lancé depuis une machine Linux de votre réseau local, y fait arriver Home Assistant, même derrière une IPv4 partagée. Ici, 192.168.1.50 est l'adresse locale de Home Assistant :

ssh -N -R 127.0.0.1:8123:192.168.1.50:8123 user@vps.example.fr

Par défaut, sshd n'écoute ce port transféré que sur la boucle locale du VPS, car l'option GatewayPorts vaut no. Rien n'est donc public à ce stade. Vous ajoutez ensuite sur le VPS un reverse proxy avec TLS (Caddy ou nginx) qui renvoie vers 127.0.0.1:8123. Ce qui devient public : le nom d'hôte du VPS. Ce qui est protégé : votre box n'ouvre aucun port, et vous contrôlez vous-même chaque couche. Le tunnel persistant et le proxy sont expliqués dans notre guide du tunnel inverse vers un VPS derrière un CGNAT.

Lequel choisir

Si vous voulez que cela marche sans maintenance, prenez Nabu Casa. Si vous utilisez déjà Tailscale et que le statut bêta ne vous gêne pas, Funnel suffit. Si vous avez déjà un VPS, le tunnel inverse vous laisse la main sur tout. La redirection de port est la seule option de cette liste qui ouvre un port sur votre box.

Le modèle de menace : ce que Claude peut faire chez vous

Le risque principal n'est pas l'accès distant. C'est ce que Claude peut lire et faire une fois connecté.

L'ensemble Home Assistant donne accès à tout : chaque entité, chaque journal, tout l'historique, et n'importe quelle action. Un assistant qui comprend mal une phrase peut donc couper le chauffage ou ouvrir une serrure. L'ensemble Device control ne voit que les entités exposées aux assistants vocaux. La page de Home Assistant sur l'exposition donne la raison de ce mécanisme : éviter que des appareils sensibles, comme les serrures et les portes de garage, soient commandés par erreur.

Le second risque est l'injection de prompt (prompt injection) : un texte lu par Claude qui contient des instructions. Le centre d'aide de Claude parle de serveurs malveillants qui cachent des instructions pour « try to make Claude perform unintended actions ». La documentation de Claude Code prévient aussi que les serveurs qui récupèrent du contenu extérieur exposent à ce risque. Dans une maison, ce texte peut venir de partout : le nom d'une entité créé par une intégration, une ligne de journal, le titre d'un événement d'agenda, une notification. Ce point est notre raisonnement, pas une déclaration d'Anthropic ou de Home Assistant. Le mécanisme reste le même : tout ce que Claude lit peut contenir une consigne. Les attaques de ce type sont décrites dans notre article sur l'injection de prompt dans les agents de code.

Deux garde-fous existent côté Claude. La page de Home Assistant indique que Claude demande votre permission avant d'appeler un outil. Le centre d'aide conseille de ne cliquer sur « Allow always » que pour les outils que vous laisseriez tourner sans surveillance. Attention au mode Research : il peut appeler les outils d'un connecteur sans nouvelle approbation, donc désactivez-y les outils qui modifient quelque chose. Dans Claude Code, la même question se pose avec les modes d'approbation, expliqués dans notre guide des permissions et du mode auto de Claude Code.

Une configuration plus étroite, étape par étape

L'idée : un compte à part, en lecture seule au début, qui ne voit que les entités choisies.

  1. Créez un utilisateur dédié. Dans Paramètres > Personnes, ajoutez une personne, par exemple « claude », autorisée à se connecter et sans droits d'administrateur. Claude agira avec les droits de ce compte, car c'est lui que vous utiliserez pendant la connexion OAuth.
  2. Exposez seulement ce que Claude doit voir. Dans Paramètres > Assistants vocaux, onglet Exposer, cochez les entités une par une. Laissez de côté les serrures, les portes de garage, l'alarme et les caméras.
  3. Réglez l'intégration. Dans les options de l'intégration MCP Server, désactivez « Expose all AI tools » et choisissez seulement Device control. Activez « Read-only ». Désactivez ensuite « Require an administrator account ». Home Assistant le permet ici, car il n'exige obligatoirement un administrateur que lorsque l'URL principale expose l'ensemble Home Assistant, ce qui n'est plus le cas.
  4. Connectez Claude. Sur claude.ai, ajoutez un connecteur personnalisé nommé « Home Assistant » avec l'URL https://<votre-adresse>/api/mcp. La page de Home Assistant indique de choisir « Sign in now » puis « Use Claude's published identity ». Connectez-vous avec le compte « claude », pas avec le vôtre.
  5. Vérifiez. Demandez à Claude la liste des appareils qu'il voit. Il doit citer vos entités exposées et rien d'autre. Demandez-lui ensuite d'allumer une lumière. En lecture seule, il n'a aucun outil pour le faire.
  6. Ouvrez ensuite petit à petit. Quand vous faites confiance au réglage, désactivez « Read-only ». Gardez les appareils sensibles non exposés.

Pourquoi l'URL principale et pas /api/mcp/assist ? Les deux donnent Device control sans administrateur. Mais les URL individuelles ne sont jamais en lecture seule. Seule l'URL principale vous permet de commencer en lecture seule.

Voie 2 : ha-mcp, et comment épingler sa version

ha-mcp est un serveur MCP communautaire, sous licence MIT. Son README annonce 86 outils au 15 novembre 2026, bien plus que Device control. Il se justifie si un outil précis dont vous avez besoin manque à l'intégration officielle : vérifiez dans la liste du README. Pour piloter des lumières et lire des capteurs, l'intégration officielle suffit.

Le README recommande désormais l'intégration HA-MCP, pour Home Assistant 2026.8.0 ou plus récent. Les autres méthodes sont une app (module complémentaire) sur Home Assistant OS, Docker (ghcr.io/homeassistant-ai/ha-mcp), uvx via PyPI, et le mode stdio local, que le README marque « not recommended ».

Épinglez une version stable. Des versions de développement (.devN) sont publiées à chaque push sur la branche master. Le projet le dit lui-même : « For production use, stick with stable releases. » Les exemples du README utilisent ha-mcp@latest, qui change sans prévenir : cinq versions stables sont sorties entre le 28 octobre (v9.0.0) et le 11 novembre 2026 (v9.2.0). Avec uvx, la syntaxe outil@version demande une version exacte :

uvx --python 3.14 ha-mcp@9.2.0

Avant d'épingler, regardez la page des releases du projet. La v9.2.0 sera sans doute dépassée quand vous lirez ces lignes. Montez de version volontairement, après avoir lu les notes de version. En Docker, le tag :latest pointe toujours vers la dernière version stable, jamais vers une version de développement. Choisissez quand même un tag de version précis dans la liste du dépôt, pour que chaque mise à jour soit une décision et pas une surprise.

Le compte. Le README propose deux options. La première est un jeton d'accès longue durée sur votre propre compte : s'il fuit, il marche de partout, et les modifications apparaissent sous votre nom. La seconde, plus sûre, est un compte réservé à HA-MCP, créé dans Settings > People > Add person, autorisé à se connecter, en accès local seulement. Le README précise : « Never use your own login for the second option. » Mais ce compte dédié a les droits d'administrateur activés dans le README. Ce n'est donc pas un compte à privilèges réduits. Pour Docker, le README note que les jetons non administrateurs marchent, avec des limites.

La lecture seule. ha-mcp a un réglage global « Read Only Mode ». On peut aussi ajouter /readonly au point d'entrée HTTP : cette connexion cache alors les outils d'écriture et bloque les appels qui modifient quelque chose. Le README précise que c'est un mode de connexion, pas une permission attachée aux identifiants. Les mêmes identifiants marchent toujours sur le point d'entrée normal. /readonly n'est donc pas une frontière de sécurité. La vraie frontière reste les droits du compte Home Assistant.

L'accès distant. Il est désactivé par défaut. Le README dit : « Local only? Leave remote access disabled at setup. » Pour un client dans le cloud, il propose une URL de webhook (https://<votre-domaine-ha>/api/webhook/<webhook-id>) via Nabu Casa ou un reverse proxy. Côté vie privée, le README indique qu'ha-mcp tourne localement et ne collecte pas de données personnelles.

Si vous faites tourner ha-mcp ou un autre serveur MCP sur une machine séparée, les questions d'hébergement sont traitées dans notre guide pour héberger des serveurs MCP sur un VPS.

FAQ

Faut-il un abonnement Claude Pro pour connecter Home Assistant ?

Non. Le centre d'aide de Claude indique que les connecteurs personnalisés existent sur les offres Free, Pro, Max, Ultra, Team et Enterprise. L'offre Free est limitée à un seul connecteur personnalisé, ce qui suffit pour Home Assistant. Sur Team, seuls les propriétaires de l'organisation peuvent ajouter le connecteur ; sur Enterprise, les personnes dont le rôle personnalisé inclut « Manage access to Libraries » le peuvent aussi.

Pourquoi Claude ne joint-il pas mon Home Assistant en 192.168.x.x ?

Parce que les connecteurs distants de claude.ai et Claude Desktop se connectent depuis les serveurs d'Anthropic, pas depuis votre ordinateur. Une adresse du réseau local, ou une adresse visible seulement dans un VPN comme votre tailnet, n'est pas joignable depuis ces serveurs. Il faut un accès public : Nabu Casa, Tailscale Funnel, Cloudflare Tunnel, un tunnel inverse vers un VPS ou une redirection de port.

Claude peut-il ouvrir ma serrure ou ma porte de garage ?

Avec les réglages par défaut et un compte administrateur, oui : l'ensemble Home Assistant peut lancer n'importe quelle action. Pour l'éviter, n'exposez pas ces entités aux assistants vocaux, limitez l'intégration à Device control et connectez Claude avec un compte non administrateur. Claude demande aussi votre permission avant d'appeler un outil, sauf si vous avez choisi « Allow always » ou autorisé le connecteur dans Research.

La connexion OAuth échoue. Que faut-il vérifier ?

D'abord l'URL : elle doit correspondre à l'URL interne ou externe déclarée dans Paramètres > Système > Réseau. Ensuite le proxy : s'il n'est pas déclaré comme proxy de confiance, Home Assistant bloque les requêtes. Avec Claude Code, une URL en http:// sur le réseau local fait échouer la connexion OAuth, car sur le runtime v2 Claude Code n'envoie les identifiants qu'en HTTPS ou vers localhost. Si un tunnel ou un proxy pose problème, la page de Home Assistant conseille Home Assistant Cloud.

Cet article vous a-t-il été utile ?