Home Assistant et Claude Desktop : le MCP sans URL publique

Et si vous pouviez discuter avec votre maison comme avec un assistant personnel ? Imaginez écrire dans Claude Desktop : « Quelles lumières sont encore allumées ? », « Mets le salon en ambiance lecture » ou « Pourquoi la chambre est-elle si chaude ? ». Au lieu de répondre uniquement avec ses connaissances générales, Claude pourrait interroger vos vrais équipements Home Assistant, lire les mesures qui lui sont accessibles et, avec votre autorisation, déclencher les actions prévues.

C’est tout le principe de Home Assistant + Claude Desktop via MCP : relier une intelligence artificielle capable de comprendre une demande en français au logiciel qui connaît les appareils et les états de votre logement. Ce n’est pas de la magie, ni une intelligence qui découvre toute seule vos équipements. Claude pose des questions ou appelle des outils ; Home Assistant fournit les données et exécute uniquement les commandes auxquelles il a accès.

Le concept expliqué simplement : Claude comprend, Home Assistant agit

Claude Desktop est l’interface de dialogue. Home Assistant centralise lampes, volets, prises, thermostats, capteurs et scènes. Le Model Context Protocol (MCP) est la passerelle standardisée qui permet à l’IA de découvrir les outils autorisés, de consulter leur résultat et de demander des actions. Vous n’avez donc pas à programmer une instruction complexe pour chaque phrase : l’IA traduit votre demande en appels d’outils, dans la limite des droits configurés.

Exemple concret : vous demandez « Est-ce que j’ai laissé une lumière allumée dans le salon ? ». Claude interroge l’outil Home Assistant disponible, reçoit l’état réel de la lampe et vous répond. Si vous ajoutez « Éteins-la », il peut proposer la commande correspondante. Une demande plus ambitieuse comme « Prépare la maison pour le cinéma » peut appeler une scène ou un script que vous avez préalablement défini et autorisé. Une lecture d’état, une commande et une routine sont trois capacités différentes.

Tout ce qu’il devient possible de faire avec Claude et Home Assistant

Voici les principaux cas d’usage, des plus simples aux plus avancés. Important : tout dépend des entités effectivement exposées à Assist, de l’API LLM sélectionnée dans le serveur MCP, des droits du compte et, pour certains usages, des scripts ou outils additionnels. Ce tableau n’affirme pas que toutes les fonctions sont disponibles dès la première connexion.

Trois niveaux d’usage à ne pas confondre

1. Observer : Claude lit un état ou un instantané de contexte et l’explique. C’est la meilleure première étape, sans risque de déclencher un appareil.
2. Agir : Claude demande une commande sur les équipements ou scripts autorisés. Home Assistant réalise l’action ; le résultat doit être contrôlé après coup.
3. Administrer ou analyser en profondeur : création d’automatisations sur l’instance, accès aux historiques, journaux, bases de données, caméras ou services tiers. Ces fonctions ne sont pas automatiquement incluses dans le MCP officiel limité à Assist : elles réclament des outils supplémentaires, parfois avec des privilèges élevés.

Une journée type : pourquoi c’est utile au-delà d’un interrupteur vocal

À 8 h : vous pourriez demander « Fais-moi un point rapide : température des pièces, lumières allumées et fenêtres restées ouvertes ». Claude synthétise les seules valeurs retournées par Home Assistant. À 19 h : « Active mon mode soirée » déclenche, si vous l’avez prévu, un script limité aux lampes et volets autorisés. Le week-end : « Propose-moi une automatisation pour limiter les lumières inutiles » produit un YAML que vous relisez et testez, sans modification cachée de l’installation.

La vraie valeur est donc de regrouper plusieurs informations, comprendre une intention et orchestrer des outils existants par le langage naturel. Mais Claude ne doit pas inventer l’état d’un appareil ni disposer par défaut d’un accès administrateur à votre maison.

Pourquoi parler de « MCP sans URL publique » ?

Normalement, un connecteur distant interroge Home Assistant depuis le cloud du fournisseur d’IA : une adresse privée comme 192.168.1.50 est alors inaccessible. Le montage de cet article utilise une autre voie : Claude Desktop → petit proxy MCP exécuté sur votre PC/Mac → Home Assistant sur le réseau local ou via VPN. Il évite de publier Home Assistant sur Internet pour cet usage. Attention : cela ne rend pas Claude lui-même local ou hors ligne ; les informations remontées à Claude peuvent toujours passer par son service cloud.

La suite du tutoriel montre précisément comment relier ces composants, restreindre les accès, copier une configuration JSON reproductible et valider une première action domotique. Ce guide utilise Home Assistant avec l’intégration officielle Model Context Protocol Server, Claude Desktop, et mcp-proxy sur l’ordinateur. Les adresses, entités et commandes sont des exemples à adapter ; ils ne constituent pas le compte rendu d’un essai matériel réel.

• Réseau : Home Assistant reste à l’adresse privée http://192.168.1.50:8123, sans redirection de port.
• Technique : le proxy convertit stdio côté Claude Desktop en Streamable HTTP côté Home Assistant.
• Permissions : limiter les API LLM, les entités exposées à Assist et les droits du compte utilisé.
• Confidentialité : une liaison domestique locale et un modèle d’IA hébergé dans le cloud sont deux notions différentes.

1. Comprendre ce que relie réellement MCP

Le Model Context Protocol permet à un client d’IA de découvrir des outils, de recevoir des informations structurées et de demander leur exécution. Ici, Home Assistant est le serveur MCP : il expose une sélection d’outils issus de ses API LLM. Claude Desktop est le client qui demande une lecture d’état ou l’exécution d’une action.

Claude Desktop (application sur le PC/Mac)
          |  protocole MCP sur stdio
          v
   mcp-proxy (processus local)
          |  MCP Streamable HTTP + Bearer token
          |  réseau privé / VPN
          v
http://192.168.1.50:8123/api/mcp
          |
          v
Home Assistant -> API LLM sélectionnée -> entités/actions autorisées

Le proxy ne publie aucun service entrant sur la box : il initie une connexion sortante du PC vers Home Assistant. En revanche, la conversation avec Claude relève toujours du service Claude. Si vous voulez également exécuter le modèle localement, le sujet est différent : voir notre dossier Ollama, LM Studio, llama.cpp ou vLLM pour Home Assistant.

Connecteur Claude classique ou véritable liaison locale ?

La documentation Home Assistant actuelle insiste sur le fait que le connecteur Claude passe par le cloud, y compris depuis l’application Desktop. Le fichier claude_desktop_config.json correspond à une configuration de serveur MCP local distincte : ne les confondez pas.

2. Préparer Home Assistant : limiter les permissions avant de brancher l’IA

1. Dans Paramètres → Appareils et services, ajoutez l’intégration Model Context Protocol Server, si elle n’est pas déjà installée.
2. Dans Paramètres → Système → IA, relevez l’URL MCP proposée par votre version. Pour une installation standard, la route de référence est /api/mcp ; si votre interface donne une route plus spécifique, préférez celle-ci.
3. Ouvrez la configuration du serveur MCP. Sur les versions récentes, l’option Expose all LLM APIs peut être activée par défaut. Pour ce tutoriel, désactivez-la et choisissez seulement l’API nécessaire au contrôle via Assist.
4. Vérifiez l’option Require an administrator account. Sur certaines versions, elle est activée par défaut : utilisez un compte dédié avec les droits strictement nécessaires et ne la désactivez que si le scénario et l’API le permettent.
5. Dans Paramètres → Assistants vocaux → Exposer, ne rendez visibles que deux ou trois entités non sensibles, par exemple light.lampe_salon et light.entree. Évitez au départ serrures, alarme, chauffage critique et ouvre-portail.

Point expert : « My MCP » et les API LLM élargies peuvent exposer davantage de fonctions que le seul contrôle de quelques lampes. L’exposition des entités à Assist ne remplace pas le filtrage des API MCP et les permissions utilisateur. Pour une première connexion, privilégiez un périmètre restreint plutôt que le contrôle global de l’installation.

Créez ensuite un jeton d’accès longue durée dans le profil Home Assistant, onglet Sécurité. Il sera utilisé localement par le proxy. Un jeton reste un secret : ne le publiez pas, ne l’insérez pas dans des captures d’écran et révoquez-le en cas de fuite.

3. Installer le proxy MCP sur macOS ou Windows

Le projet libre sparfenyuk/mcp-proxy fait la passerelle entre les transports stdio et Streamable HTTP. L’outil uv d’Astral permet de l’installer sans gérer manuellement un environnement Python. Si uv n’est pas présent, installez-le depuis la documentation officielle d’uv, puis exécutez :

uv tool install mcp-proxy
mcp-proxy --version

Sous macOS/Linux, localisez l’exécutable avec :

command -v mcp-proxy
# Exemple : /Users/votre-utilisateur/.local/bin/mcp-proxy

Sous Windows PowerShell :

uv tool install mcp-proxy
where.exe mcp-proxy
# Exemple : C:\Users\VotreNom\.local\bin\mcp-proxy.exe

Gardez le chemin retourné : Claude Desktop n’hérite pas toujours du même PATH qu’un terminal lancé manuellement. Un chemin absolu évite le classique « Failed to start MCP server ».

4. Configurer Claude Desktop : le JSON complet

Fermez Claude Desktop avant de modifier sa configuration. Le fichier se trouve normalement ici :

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows : %APPDATA%\Claude\claude_desktop_config.json

Exemple pour un Mac dont Home Assistant est à 192.168.1.50. Remplacez le chemin de l’exécutable, l’adresse et le jeton. Ce JSON est l’objet complet pour une configuration sans autre serveur ; si votre fichier possède déjà mcpServers, ajoutez seulement l’entrée home-assistant-local sans effacer les autres.

{
  "mcpServers": {
    "home-assistant-local": {
      "command": "/Users/votre-utilisateur/.local/bin/mcp-proxy",
      "args": [
        "--transport=streamablehttp",
        "--stateless",
        "http://192.168.1.50:8123/api/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "REMPLACER_PAR_VOTRE_JETON"
      }
    }
  }
}

Sous Windows, remplacez seulement le champ command par le chemin de mcp-proxy.exe renvoyé par where.exe, en doublant les antislashs dans le JSON (par exemple C:\\Users\\VotreNom\\.local\\bin\\mcp-proxy.exe). Ne mettez pas le token dans args : la variable API_ACCESS_TOKEN est interprétée par mcp-proxy comme un en-tête Bearer.

Sur macOS, restreignez les permissions du fichier qui contient le jeton :

chmod 600 "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Après enregistrement, quittez complètement Claude Desktop et relancez-le. Vérifiez qu’un serveur local nommé home-assistant-local et ses outils apparaissent. La disponibilité des outils dépend de l’API LLM choisie et des réglages de votre installation.

5. Cas concret : analyser le salon et lancer un éclairage doux

Prenons une maison avec deux équipements fictifs : light.lampe_salon (lampe dimmable) et light.entree (éclairage d’entrée). Après leur exposition à Assist, on peut réaliser une séquence progressive qui distingue consultation et action.

Étape A — Demander l’état sans modifier la maison

Prompt de test à saisir dans Claude Desktop :

« Consulte Home Assistant : la lampe du salon et la lumière de l’entrée sont-elles allumées ? Donne les noms exacts des entités et leur état actuel. N’exécute aucune action. Si une donnée est indisponible, signale-le. »

Claude doit découvrir les outils MCP disponibles puis appeler celui qui permet la consultation du contexte. Les noms réels des outils peuvent changer selon la version et l’API. La réponse doit être fondée sur l’état renvoyé par Home Assistant, pas sur une déduction du modèle.

Étape B — Demander une action précise, puis vérifier son résultat

« Allume uniquement la lampe du salon à 35 % de luminosité, sans toucher à la lumière de l’entrée. Demande ma confirmation si l’appel d’outil le requiert, puis relis l’état de la lampe pour vérifier. »

Dans le flux attendu, Claude propose un appel d’outil, vous l’autorisez, Home Assistant effectue l’action, puis Claude interroge à nouveau l’état. N’en déduisez pas qu’une commande a réussi simplement parce que le texte final dit « c’est fait » : exigez une relecture réelle. Ne testez pas d’abord avec une prise électrique alimentant un appareil dangereux.

Étape C — Encapsuler une commande fiable dans un script Home Assistant

Pour ne pas laisser un LLM interpréter librement une multitude de paramètres, vous pouvez créer un script déterministe. Dans scripts.yaml, cet exemple active une seule lampe. Les entités sont à adapter à votre installation. Prérequis : la lampe doit accepter le réglage de luminosité et la température de couleur à 3 000 K. Si elle ne prend en charge que la variation de luminosité, supprimez la ligne color_temp_kelvin: 3000 et retirez la mention « blanc chaud » de la description.

mode_lecture_mcp:
  alias: "Mode lecture salon"
  description: >
    Allume uniquement la lampe du salon à 35 %,
    en blanc chaud. Ne touche jamais aux autres
    lumières, à l'alarme ou aux accès.
  sequence:
    - action: light.turn_on
      target:
        entity_id: light.lampe_salon
      data:
        brightness_pct: 35
        color_temp_kelvin: 3000
  mode: single

Rechargez les scripts après validation de la configuration et testez-le depuis Home Assistant avant d’impliquer Claude. Sur les versions et API de conversation compatibles, les scripts exposés à Assist peuvent être proposés au LLM comme outils nommés. Activez explicitement l’exposition du script aux assistants vocaux, ajoutez une description claire, puis vérifiez dans Claude qu’il est effectivement disponible. Ce bloc est du YAML à installer manuellement, pas une automatisation que le MCP officiel crée tout seul.

Le gain technique est important : Claude comprend une intention (« mode lecture »), mais Home Assistant conserve la logique réelle (une lampe, une luminosité, aucune action annexe). Voir également le guide officiel Exposer des scripts aux agents LLM.

6. Vérifier la liaison et diagnostiquer les erreurs

Avant d’accuser Claude, vérifiez d’abord que l’ordinateur atteint Home Assistant. Depuis le même PC/Mac que Claude Desktop :

curl --connect-timeout 5 -I http://192.168.1.50:8123/

Une réponse HTTP signifie que le serveur web Home Assistant est joignable. Ce test ne valide ni le MCP ni le jeton. Pour diagnostiquer précisément, consultez les journaux MCP dans Claude Desktop → Paramètres → Développeur → serveur → journaux, lorsqu’ils sont disponibles sur votre version.

Autre piège : le connecteur Claude → Connectors → Add custom connector ne pourra pas atteindre 192.168.1.50 depuis le cloud d’Anthropic. Si vous utilisez ce menu pour une IP privée, changer le jeton ne corrigera pas le problème : revenez à la configuration mcpServers locale.

7. Modèle de sécurité : ce qui reste local et ce qui ne l’est pas

• Surface réseau : aucune redirection de port ni URL publique n’est nécessaire dans le scénario local. En dehors du domicile, connectez d’abord l’ordinateur au VPN ; ne publiez pas le port 8123 pour « faciliter » le tutoriel.
• Secret : le jeton en clair figure dans la configuration de Claude Desktop. Protégez la session de l’ordinateur, restreignez les permissions du fichier et révoquez ce jeton s’il a pu fuiter.
• Autorisation : un compte dédié, un ensemble réduit d’API LLM et une liste courte d’entités sont trois contrôles distincts. Les droits administrateur par défaut du serveur MCP récent justifient une vérification explicite.
• Actions physiques : conservez les confirmations d’appels d’outils. Ne branchez jamais une commande ouverte sur une serrure, un portail, une alarme ou un chauffage dangereux sans garde-fous indépendants.
• Données : le transport entre votre PC et Home Assistant est local, mais le modèle Claude reste hébergé dans le cloud. Évitez de partager les heures de présence, états d’alarme ou historiques détaillés si votre politique de confidentialité l’interdit.

Ne confondez pas les deux intégrations Home Assistant : Model Context Protocol Server expose des outils Home Assistant à un client IA ; Model Context Protocol (client) permet au contraire à Home Assistant de consommer des serveurs MCP externes. Les rôles sont inversés. Pour approfondir l’architecture, lisez applications ou intégrations Home Assistant : que choisir ?.

8. Peut-on demander à Claude d’écrire des automatisations ?

Oui, pour rédiger, expliquer ou auditer du YAML. Non, pas automatiquement pour modifier votre instance avec le périmètre minimal utilisé dans ce tutoriel. Les outils de l’API Assist sont d’abord destinés à agir sur les éléments exposés. Certains serveurs communautaires disposent d’outils supplémentaires qui permettent d’éditer automations, scripts ou dashboards : c’est une augmentation majeure des privilèges, qui mérite une installation isolée et une vérification des sources.

Une méthode robuste consiste à demander à Claude un fichier YAML sans exécution, vérifier les entités et les conditions, puis appliquer et tester le résultat dans Home Assistant. Pour un usage quotidien, préférez un script limité et documenté à un outil générique offrant l’administration complète.

FAQ — Claude Desktop et Home Assistant MCP

Faut-il Home Assistant Cloud ou un certificat HTTPS ?

Non, pas pour le proxy local sur réseau privé : une URL http://192.168.x.x:8123 peut suffire. Une configuration avec connecteur distant exige, elle, une URL HTTPS accessible depuis les serveurs du fournisseur. Sur réseau Wi-Fi non fiable, préférez TLS ou un VPN.

Pourquoi la connexion ne marche-t-elle pas depuis claude.ai ?

Le navigateur ou le connecteur cloud ne peut pas rejoindre l’adresse privée de votre maison. Le mécanisme local décrit ici requiert l’application Claude Desktop installée, un processus MCP lancé sur ce même ordinateur et un accès réseau vers Home Assistant.

Le proxy est-il réellement local si Claude est en ligne ?

Oui pour le segment Claude Desktop → proxy → Home Assistant ; non pour le traitement du langage, qui utilise toujours les services de Claude. La confidentialité dépend donc à la fois du périmètre de données remontées par les outils et du service de modèle choisi.

Quelle URL MCP choisir ?

Utilisez l’URL affichée par Paramètres → Système → IA lorsque votre version la fournit. /api/mcp est l’endpoint historique du serveur officiel ; certaines API LLM disposent d’un chemin spécialisé. Ne remplacez pas arbitrairement l’URL configurée par un ancien endpoint SSE.

Les références techniques pour aller plus loin

• Home Assistant — Model Context Protocol Server (fonctionnement, permissions et configuration actuelle).
• mcp-proxy — dépôt et documentation officielle (transports, variables d’environnement, installation).
• Home Assistant — exposer les entités à Assist (réduction des droits).
• Anthropic — serveurs MCP locaux sur Claude Desktop (compatibilité et dépannage).

Verdict : pour les passionnés de domotique qui refusent de rendre Home Assistant accessible sur Internet, le proxy MCP local est un compromis pratique. La vraie expertise n’est pas seulement de faire fonctionner un JSON : elle consiste à limiter les API, borner les actions et vérifier les résultats. Commencez par la lecture d’état et un éclairage sans risque avant d’envisager des commandes plus ambitieuses.