Home Assistant MCP Server : contrôler HA depuis Claude Desktop

Home Assistant 2026.6, sorti le 4 juin 2026, embarque une nouvelle intégration native : MCP Server. Pour la première fois, vous pouvez connecter Claude Desktop directement à votre instance HA, sans add-on tiers, sans configuration complexe. Claude lit l'état de vos entités, interroge votre historique énergétique, et — avec la solution communautaire ha-mcp — crée des automatisations YAML complètes depuis une simple phrase en français.

Ce guide couvre les deux approches disponibles en 2026 : l'intégration officielle de HA 2026.6, sobre et suffisante pour contrôler et interroger votre maison, et ha-mcp, la version communautaire à 84 outils qui permet de modifier la configuration de HA depuis Claude. Vous saurez laquelle installer selon vos besoins, et comment configurer Claude Desktop pour les deux.

MCP + Home Assistant : l'IA qui agit, pas juste qui répond

Assist vs MCP : deux paradigmes différents

Vous connaissez probablement Assist, le système de commandes vocales natif de Home Assistant. Avec Assist, chaque interaction est indépendante : vous dites "allume la lumière du salon", la phrase est interprétée, l'action exécutée. L'IA ne sait pas ce qui s'est passé avant, elle ne connaît pas l'état des autres pièces, et elle ne peut pas enchaîner plusieurs actions complexes sans que vous les détailliez une par une.

Le Model Context Protocol (MCP) fonctionne selon un paradigme radicalement différent. C'est un standard ouvert développé par Anthropic qui permet à un client IA — Claude Desktop dans notre cas — d'obtenir un contexte complet sur un système externe et d'y effectuer des opérations structurées. Concrètement, quand Claude Desktop se connecte à votre MCP Server Home Assistant, il peut :

• lire l'état en temps réel de toutes vos entités exposées ;
• interroger l'historique et les statistiques d'énergie ;
• appeler des services HA (allumer une lumière, déclencher un script, etc.) ;
• avec ha-mcp : créer et modifier des automatisations, gérer les intégrations HACS, éditer les dashboards.

Claude ne reçoit plus une commande isolée — il dispose d'une fenêtre sur votre installation, ce qui lui permet de poser des questions pertinentes, de détecter des incohérences, et de construire des automatisations qui utilisent vos entity IDs réels.

Ce que HA 2026.6 change concrètement

Avant la 2026.6, connecter un client IA à Home Assistant via MCP nécessitait d'installer un add-on communautaire, de configurer un serveur externe ou d'écrire des scripts. L'intégration mcp_server native change la donne : elle s'active en quelques clics depuis le menu des intégrations, aucune dépendance externe n'est nécessaire, et elle s'appuie sur l'Assist API, la même API qui alimente les assistants vocaux de HA.

Le transport utilisé est le Streamable HTTP, un protocole stateless robuste qui permet au client MCP de communiquer avec HA sans maintenir une connexion permanente. Côté sécurité, l'accès est contrôlé par un Long-lived access token et limité aux entités que vous avez explicitement exposées.

Officielle vs ha-mcp : comment choisir ?

Il existe aujourd'hui deux options sérieuses pour connecter Claude Desktop à Home Assistant via MCP. Voici le comparatif pour décider rapidement :

Critère	Intégration officielle (HA 2026.6+)	ha-mcp (communautaire)
Installation	Natif HA, aucun add-on	Add-on HA ou pip/uvx
Outils disponibles	Lecture + contrôle entités via Assist API	84 outils sur 26 catégories
Créer des automatisations	Non	Oui (YAML complet)
Gérer HACS	Non	Oui
Modifier les dashboards	Non	Oui
Historique et énergie	Partiel	Complet
Maintenance	Équipe Home Assistant	Communauté open source
Version HA minimale	2026.6+	Toutes versions récentes

Règle de décision : si vous voulez interroger l'état de votre maison et contrôler des appareils depuis Claude, l'intégration officielle suffit et s'installera en cinq minutes. Si vous voulez que Claude écrive des automatisations, installe des intégrations HACS ou modifie votre configuration HA, ha-mcp est indispensable — et ses capacités supplémentaires justifient le léger surcoût d'installation.

Option A — Intégration officielle MCP Server (HA 2026.6+)

Activer l'intégration dans Home Assistant

1. Dans HA, allez dans Paramètres → Appareils et services → Intégrations.
2. Cliquez sur Ajouter une intégration et recherchez Model Context Protocol Server.
3. Confirmez l'ajout. Aucune configuration supplémentaire n'est requise à cette étape.

L'intégration expose un endpoint MCP sur votre instance HA. L'URL complète de connexion est : http://homeassistant.local:8123/api/mcp — ou l'IP de votre serveur si la résolution DNS locale ne fonctionne pas sur votre réseau (http://192.168.1.X:8123/api/mcp).

Configurer les entités exposées

Le MCP Server officiel donne accès à Claude uniquement aux entités que vous avez explicitement exposées dans le menu Voice Assistants. Si vous avez déjà configuré Assist, vos entités sont probablement déjà exposées.

1. Allez dans Paramètres → Assistants vocaux → Entités exposées.
2. Activez le toggle pour chaque entité que Claude doit pouvoir lire et contrôler.
3. Conseil : limitez aux entités vraiment utiles (lampes, capteurs de présence, thermostats, prises). Inutile d'exposer les internal sensors ou les entités techniques HA.

Générer le Long-lived access token

Claude Desktop a besoin d'un token pour s'authentifier auprès de votre HA. Ce token est propre à votre compte utilisateur et hérite de ses permissions.

1. Cliquez sur votre nom d'utilisateur en bas à gauche de l'interface HA (ou allez dans Profil).
2. Faites défiler jusqu'à la section Tokens d'accès à long terme.
3. Cliquez sur Créer un token, nommez-le Claude Desktop MCP.
4. Copiez immédiatement le token affiché — il ne sera plus visible ensuite.

Option B — ha-mcp : le serveur communautaire aux 84 outils

ha-mcp est un projet open source développé par la communauté Home Assistant. Il se connecte à HA via l'API REST et l'API WebSocket, ce qui lui permet d'effectuer des opérations structurelles impossibles via la seule Assist API : créer des automatisations, modifier le registre d'entités, installer des intégrations HACS, générer des dashboards.

Installation avec uvx sur votre PC (recommandé pour Claude Desktop)

C'est la méthode recommandée si vous utilisez Claude Desktop : ha-mcp tourne directement sur le PC qui fait tourner Claude Desktop, communique avec HA via l'API, et s'intègre via stdio — sans proxy, sans port supplémentaire à ouvrir.

# Avec uvx — pas d'installation permanente, toujours à jour
uvx ha-mcp@latest

# Alternative avec pip
pip install ha-mcp
ha-mcp

La configuration se fait via les variables d'environnement dans claude_desktop_config.json, comme décrit dans la section suivante. C'est tout — ha-mcp démarre automatiquement quand Claude Desktop en a besoin.

ha-mcp dispose d'une page de réglages locale qui vous permet d'activer ou désactiver individuellement chacun des 84 outils. Pour y accéder, demandez simplement à Claude (une fois connecté) : "Ouvre la page de réglages ha-mcp." L'URL est retournée dans la réponse de l'outil ha_get_overview.

Installation en tant qu'add-on HA (si ha-mcp doit tourner dans HA OS)

Cette méthode est à privilégier si vous souhaitez que ha-mcp s'exécute à l'intérieur de Home Assistant OS ou Supervised, indépendamment du PC faisant tourner Claude Desktop.

1. Dans HA : Paramètres → Add-ons → Boutique des add-ons.
2. Si ha-mcp n'apparaît pas dans la boutique, ajoutez son dépôt manuellement : cliquez sur le ⋮ en haut à droite → Dépôts → ajoutez https://github.com/homeassistant-ai/ha-mcp.
3. Installez l'add-on, entrez l'URL de votre HA et votre Long-lived access token dans la configuration.
4. Démarrez l'add-on. Il expose un endpoint MCP que Claude Desktop peut interroger via le réseau local.

Connecter Claude Desktop à Home Assistant

Localiser le fichier de configuration

Claude Desktop stocke sa configuration MCP dans un fichier JSON dont l'emplacement dépend de votre OS :

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

Ouvrez ce fichier avec un éditeur de texte (VS Code, Notepad++, nano). S'il n'existe pas, créez-le.

Configuration pour l'intégration officielle (Streamable HTTP)

L'intégration officielle utilise le transport Streamable HTTP. Claude Desktop (application bureau) ne supporte pas le champ url dans claude_desktop_config.json — la configuration s'ajoute via l'interface graphique.

Option A — via l'interface Claude Desktop (recommandée) :
Dans Claude Desktop : Paramètres → Connecteurs → Ajouter un connecteur personnalisé
URL : http://homeassistant.local:8123/api/mcp
Ajoutez un header Authorization avec la valeur : Bearer VOTRE_TOKEN_ICI

Option B — via claude_desktop_config.json avec mcp-remote (nécessite Node.js) :

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://homeassistant.local:8123/api/mcp",
        "--header",
        "Authorization:Bearer VOTRE_TOKEN_ICI"
      ]
    }
  }
}

Remplacez homeassistant.local:8123 par l'adresse IP réelle de votre serveur si la résolution DNS locale ne fonctionne pas. Remplacez VOTRE_TOKEN_ICI par le token généré précédemment. Si votre HA est accessible via Nabu Casa, remplacez l'URL locale par votre URL cloud (https://xxxxx.ui.nabu.casa/api/mcp).

Configuration pour ha-mcp (uvx)

{
  "mcpServers": {
    "home-assistant": {
      "command": "uvx",
      "args": ["ha-mcp@latest"],
      "env": {
        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
        "HOMEASSISTANT_TOKEN": "VOTRE_TOKEN_ICI"
      }
    }
  }
}

Vérifier la connexion

1. Fermez complètement Claude Desktop (pas juste la fenêtre — quittez l'application).
2. Relancez Claude Desktop.
3. Dans une nouvelle conversation, cherchez le picto marteau (outils MCP) en bas de la zone de saisie. Cliquez dessus : home-assistant doit apparaître dans la liste.
4. Testez avec : "Liste-moi les lumières disponibles dans Home Assistant."

Si la connexion échoue, vérifiez deux points : une erreur 401 indique que le token est incorrect ou expiré. Une erreur 404 signifie que l'intégration MCP Server n'est pas activée dans HA, ou que l'URL est incorrecte.

Ce que Claude peut vraiment faire — 5 exemples concrets

1. Interroger l'état des entités en temps réel

C'est la base, disponible avec les deux options :

Prompt : "Quelles lampes sont allumées dans le salon en ce moment, et à quelle luminosité ?"

Claude interroge toutes les entités light.* correspondantes et retourne un résumé lisible avec l'état, la luminosité en pourcentage et la couleur si disponible. Pratique pour diagnostiquer une lumière oubliée sans ouvrir le tableau de bord.

2. Créer une automatisation en langage naturel (ha-mcp)

Prompt : "Crée une automatisation qui éteint toutes les lumières du rez-de-chaussée quand personne n'est à la maison depuis 10 minutes."

ha-mcp récupère vos entity IDs de lampes et vos entités person.*, vérifie qu'aucune automatisation similaire n'existe déjà, puis génère et enregistre le YAML directement dans HA (les prenom_1 / prenom_2 sont remplacés par vos entity IDs réels) :

alias: Éteindre lumières rez-de-chaussée — départ
description: Généré via ha-mcp + Claude Desktop
trigger:
  - platform: state
    entity_id:
      - person.prenom_1
      - person.prenom_2
    to: not_home
    for:
      minutes: 10
condition:
  - condition: state
    entity_id: person.prenom_1
    state: not_home
  - condition: state
    entity_id: person.prenom_2
    state: not_home
action:
  - action: light.turn_off
    target:
      area_id: rez_de_chaussee
mode: single

L'automatisation apparaît immédiatement dans votre liste HA, activée et prête à fonctionner. Vous pouvez demander à Claude de la modifier, la désactiver ou la supprimer avec une nouvelle phrase.

3. Analyser la consommation énergie (ha-mcp)

Prompt : "Compare ma consommation électrique entre cette semaine et la semaine dernière. Quel appareil consomme le plus ?"

ha-mcp interroge l'API statistiques de HA, compare les données hebdomadaires, et produit un résumé avec les appareils classés par consommation. Utile pour identifier des appareils énergivores sans creuser dans les graphiques du tableau de bord Énergie.

4. Diagnostiquer des entités indisponibles

Prompt : "J'ai des entités en statut unavailable. Lesquelles et depuis combien de temps ?"

Claude liste toutes les entités indisponibles avec leur dernier état connu et l'horodatage du changement. Gain de temps considérable par rapport à la navigation manuelle dans le journal HA pour identifier un appareil tombé hors ligne.

5. Installer une intégration HACS (ha-mcp uniquement)

Prompt : "Installe l'intégration HACS 'Garbage Collection' et configure-la pour les poubelles jaunes le lundi et les vertes le vendredi."

ha-mcp dispose des outils HACS dans ses 84 outils : il peut rechercher, installer et paramétrer des intégrations communautaires sans que vous ouvriez l'interface HA. Pratique pour les utilisateurs qui gèrent plusieurs instances ou qui automatisent leur setup depuis un script.

Sécurité et local-first : ce que voit vraiment Claude

Vos données restent sur votre réseau local

Un point important souvent mal compris : les deux solutions fonctionnent localement. Claude Desktop envoie la requête au MCP Server (HA ou ha-mcp), qui s'exécute sur votre réseau local et interroge votre instance HA sans sortir de votre LAN. Ce qui transite par les serveurs d'Anthropic, c'est uniquement le texte de votre conversation — les données de vos entités, automatisations et historiques ne quittent pas votre réseau.

Cette architecture est fondamentalement différente des assistants cloud qui envoient vos données domotiques à des serveurs distants pour les interpréter.

Contrôler ce que Claude peut voir

Avec l'intégration officielle, le périmètre est défini par la page Entités exposées : seules les entités cochées sont accessibles. C'est le point de contrôle le plus simple.

Avec ha-mcp, l'accès est plus large par design. Utilisez la page de réglages locale de ha-mcp pour désactiver les catégories d'outils que vous ne souhaitez pas exposer — par exemple, désactiver les outils HACS ou System si vous voulez restreindre Claude à la lecture et au contrôle d'entités uniquement.

Bonnes pratiques pour le token d'accès

• Nommez explicitement chaque token selon son usage : Claude Desktop MCP — Juin 2026.
• Ne commitez jamais un fichier contenant un token dans un dépôt git.
• Si vous soupçonnez une compromission, révoquez le token immédiatement depuis Profil → Tokens d'accès à long terme → Supprimer.
• Si votre HA est accessible via un tunnel Nabu Casa, remplacez homeassistant.local:8123 par votre URL Nabu Casa dans la config JSON. Les données transitent alors par les serveurs Nabu Casa — pratique pour accéder à HA depuis l'extérieur, mais vos données sortent du réseau local.

Aller plus loin — combiner MCP et assistant vocal local

Si vous avez déjà mis en place un assistant vocal local avec un Wyoming Satellite sur ESP32-S3, MCP et Assist coexistent sans conflit sur le même HA. Les deux systèmes sont complémentaires :

• Assist + Wyoming Satellite : commandes vocales temps réel, réponse en moins d'une seconde, fonctionne sans internet.
• Claude Desktop via MCP : configuration, diagnostic, création d'automatisations complexes — là où une conversation structurée est plus adaptée qu'une commande vocale.

Pour aller encore plus loin côté matériel tout-en-un — microphone, haut-parleur et ESP32-S3 intégrés dans un boîtier compact compatible Wyoming Satellite :

Pour approfondir les capacités IA de Home Assistant côté modèles locaux, consultez également notre guide sur Ollama et Home Assistant : faire tourner un LLM sur votre propre machine pour des automatisations IA entièrement hors cloud.