ha-mcp Home Assistant : sécuriser un agent IA à la maison

ha-mcp Home Assistant : serveur MCP non officiel (MIT) pour piloter sa maison avec un agent IA. Jeton, lecture seule, approbation et journaux à lire.
ha-mcp Home Assistant : sécuriser un agent IA à la maison

ha-mcp Home Assistant : c’est un serveur MCP non officiel, publié sur GitHub par le dépôt homeassistant-ai/ha-mcp, qui permet à un assistant IA (Claude, ChatGPT, Gemini CLI…) de lire et de piloter une installation Home Assistant en langage naturel. Selon sa page GitHub le 27 octobre 2026, le dépôt compte environ 5 300 étoiles (GitHub affiche « 5.3k », valeur arrondie) et 255 forks, sous licence MIT.

Pour une équipe SRE, l’intérêt dépasse la domotique. Ce dépôt est un cas d’école : un agent reçoit les clés d’une « petite production » faite de lumières, de serrures, d’automatisations et de sauvegardes. Les questions utiles sont donc : qui peut appeler le serveur, avec quels droits, et que se passe-t-il si une action est irréversible ? Cet article suit le README, SECURITY.md, la FAQ du dépôt et le fichier LICENSE, relus aujourd’hui.

Précision d’honnêteté : span.observer est un blog indépendant, sans lien avec Home Assistant ni avec les auteurs du projet, et n’a ni installé ni lancé ha-mcp. Le projet se décrit lui-même comme « The Unofficial and Awesome Home Assistant MCP Server ». Les captures ci-dessous sont des extraits rendus à partir des fichiers du dépôt.

ha-mcp Home Assistant : ce que dit le dépôt

  • Licence : le fichier LICENSE est une licence MIT.
  • Langage et cadre : Python 3.13 ou plus (requires-python = ">=3.13,<3.15" dans pyproject.toml), construit avec FastMCP, d’après le README.
  • Version : pyproject.toml et le CHANGELOG indiquent la version 8.7.0 du 14 octobre 2026. Je n’ai pas pu lire de numéro de release sur la page GitHub ; le dernier commit lu date du 26 octobre 2026.
  • Périmètre : le README annonce 87 outils : recherche d’entités, appel de services, automatisations, scripts, tableaux de bord, historique, journaux, sauvegardes, registre des appareils, redémarrage de Home Assistant.
  • Différence avec le serveur MCP intégré : d’après le README, celui de Home Assistant s’appuie sur Assist et ne voit que les entités exposées à Assist ; ha-mcp couvre « tout ce qui est dans Home Assistant », y compris la création et la modification de configuration.

Cette différence est le cœur du sujet : plus l’agent peut configurer, plus la surface de risque grandit.

Serveur MCP Home Assistant : la surface de risque

Trois points de SECURITY.md méritent d’être lus avant toute installation.

  • Un client authentifié est un « principal de confiance ». Le fichier dit que ha-mcp ne cherche pas à se défendre contre un client MCP malveillant ou compromis, et que l’injection de prompt est de la responsabilité du client.
  • Les droits viennent du jeton. ha-mcp utilise le jeton d’accès longue durée fourni ; avec un jeton d’administrateur, il peut faire des opérations d’administrateur. Le projet attend un jeton d’administrateur et conseille, pour limiter l’agent, ses politiques de sécurité par outil ou la désactivation d’outils plutôt qu’un jeton non administrateur.
  • Le réseau local est la zone de confiance. En mode standard, l’authentification repose sur le secret dans le chemin de l’URL ; tout pair qui atteint ce chemin est traité comme de confiance. Par défaut, les points d’entrée HTTP écoutent sur 0.0.0.0 ; MCP_HOST=127.0.0.1 restreint à la machine locale.
Extraits de SECURITY.md du dépôt homeassistant-ai/ha-mcp : un client MCP authentifié est un principal de confiance, les droits dépendent du jeton fourni, et MCP_HOST=127.0.0.1 limite l'écoute à la machine locale
Source : github.com

Le même fichier précise qu’en mode standard tous les clients qui partagent le même secret ont un accès identique, sans isolation entre clients. Pour un accès depuis Internet, SECURITY.md oriente vers le mode OAuth (décrit comme bêta) ou OIDC derrière un proxy inverse TLS. Pour les principes généraux, voir sécuriser un serveur MCP et les leçons SRE du MCP grand public.

Limiter l’agent : lecture seule, politiques, approbation

Le README liste dans la catégorie « Safety » : un mode lecture seule, l’activation ou la désactivation par outil, des politiques de sécurité d’outils (approbation par l’utilisateur) et des sauvegardes automatiques des modifications.

Lecture seule par connexion

Selon le README, ajouter /readonly à l’URL du serveur HTTP restreint cette connexion au mode lecture seule, pendant que d’autres clients gardent un accès normal. Les outils d’écriture sont masqués et leurs appels bloqués, y compris via des outils en cache.

Extrait du README de ha-mcp : deux adresses d'exemple, l'une normale et l'autre se terminant par /readonly, et la règle qui masque les outils d'écriture sur la connexion en lecture seule
Source : github.com

Attention, le README précise que c’est un mode de connexion et non une permission sur l’identifiant : les mêmes identifiants fonctionnent sur l’adresse normale. Un secret qui fuite donne donc l’accès complet.

Mode lecture seule global

La documentation de l’application (add-on) décrit l’option read_only_mode, désactivée par défaut : elle retire les outils d’écriture de la liste et bloque toute écriture avec une erreur READ_ONLY_MODE. Les cas d’usage cités : analyse, audit, démonstration. Un redémarrage de l’application est nécessaire.

Approbation humaine des actions sensibles

La FAQ décrit des règles « Tool Security Policies » qui retiennent un appel jusqu’à approbation dans l’interface de réglages. Chaque demande est aussi annoncée sur le bus d’événements de Home Assistant sous le nom ha_mcp_approval_requested, avec les champs token, tool_name, args, created_at et expires_at.

Extrait de docs/FAQ.md de ha-mcp : une automatisation Home Assistant déclenchée par l'événement ha_mcp_approval_requested qui envoie une notification avec le nom de l'outil et ses arguments
Source : github.com

La FAQ avertit que les arguments sont tronqués s’ils sont longs, mais non masqués : un argument court est diffusé tel quel sur le bus. Approuver depuis une notification est désactivé par défaut et demande un code PIN.

Installation pas à pas

Le README recommande le composant personnalisé « HA-MCP Custom Component », installé par HACS, qui exécute le serveur dans Home Assistant. Son démarrage rapide indique la version 9.0.0 (28 octobre 2026) et suivantes : cette date est postérieure à celle de ma lecture, donc vérifiez les écrans sur votre version.

  1. Installez le composant depuis HACS (dépôt personnalisé https://github.com/homeassistant-ai/ha-mcp, catégorie Integration), puis redémarrez Home Assistant.
  2. Choisissez le compte administrateur sous lequel le serveur agit. Le README juge plus sûr de créer un compte dédié (Paramètres, Personnes) avec « Allow login », « Local access only » et « Administrator ». Un jeton sur votre propre compte « marche de partout s’il fuite ».
  3. Ajoutez l’intégration (Paramètres, Appareils et services), choisissez le mode de connexion : accès distant par webhook (commencer par « Secret URL ») et/ou accès réseau local. Les deux sont désactivés au départ.
  4. Copiez l’URL de connexion depuis l’écran Configure et collez-la dans votre client IA.

Autres méthodes selon le README : application Home Assistant (HAOS et Supervised), Docker, PyPI avec uvx, ou stdio local (déconseillé, des problèmes de transport sont signalés). Ne configurez qu’une seule méthode par client. Pour un essai sans toucher à votre maison, le README propose des scripts d’installation vers un serveur de démonstration ; vérifiez le contenu d’un script avant de l’exécuter.

Limites et points ouverts

  • Ancrage à nuancer : projet actif (nombreux contributeurs listés, CHANGELOG détaillé) mais très mouvant, avec plusieurs modes d’installation et d’authentification. Le README annonce un changement cassant en v7.3.0 et place des fonctions en bêta (fichiers, YAML, outils personnalisés). Le chiffre d’étoiles est arrondi par GitHub.
  • Dates à vérifier : le README mentionne une version 9.0.0 datée du 28 octobre 2026, alors que la version lue dans le code est 8.7.0.
  • Outils d’écriture sensibles : parmi les 87 outils figurent le redémarrage, la suppression d’appareils et d’entités, la restauration de sauvegardes et, en bêta, l’écriture de fichiers. Certaines actions ne se défont pas par un simple retour arrière.
  • Secret dans l’URL : le FAQ déconseille de le coller dans des captures, des journaux publics ou des conversations.
  • Données : PRIVACY.md dit que ha-mcp ne collecte pas de télémétrie en juin 2026 (une collecte anonyme est « prévue »), mais ce que l’agent lit transite par votre client IA et son fournisseur.
  • Projet non officiel : il n’est ni développé ni garanti par Home Assistant.

Observer le serveur MCP

La documentation lue ne décrit pas d’export de traces ni de métriques OpenTelemetry. pyproject.toml liste bien la bibliothèque opentelemetry-api parmi les dépendances, mais rien ne dit qu’elle exporte des traces : ne bâtissez pas de supervision dessus sans le vérifier. Ce que décrit la documentation :

  • Journaux du serveur : application (onglet Logs), docker logs ha-mcp pour Docker. La FAQ cite deux lignes normales : « Terminating session: None » (mode HTTP sans état) et un 405 sur un GET.
  • Diagnostics de transport HTTP : l’option HAMCP_HTTP_TRANSPORT_DIAGNOSTICS=true (désactivée par défaut, redémarrage requis) journalise au niveau INFO les volumes d’octets, la durée, les déconnexions et le type d’exception, avec un identifiant de trace généré par le serveur. Ni corps, ni identifiants, ni chemins secrets.
  • Événements d’approbation : ha_mcp_approval_requested sur le bus Home Assistant permet de compter et d’alerter sur les actions retenues.
  • Côté Home Assistant : les outils ha_get_logs et ha_get_automation_traces lisent journaux et traces d’automatisations.

Pour tracer les appels d’outils de bout en bout, c’est le client ou l’agent qui doit émettre les spans : voir observer des agents MCP avec OpenTelemetry. Un projet voisin du même type : Agent Reach.

Bonnes pratiques

  • Commencez en lecture seule (/readonly ou read_only_mode) et n’ouvrez l’écriture qu’en cas de besoin.
  • Créez un compte administrateur dédié plutôt que d’utiliser votre jeton personnel.
  • Gardez l’accès local ; si l’accès distant est nécessaire, préférez une authentification Home Assistant ou OIDC au secret seul.
  • Exigez une approbation humaine pour les outils destructeurs (suppression, restauration, redémarrage).
  • Faites tourner un secret exposé et surveillez les journaux ; voir les garde-fous des agents IA.

Questions fréquentes

ha-mcp est-il un projet officiel de Home Assistant ?

Non. Le dépôt se présente comme « Unofficial ». Home Assistant propose de son côté un serveur MCP intégré, que le README compare à ha-mcp.

Un agent peut-il vraiment tout modifier ?

Il peut ce que permet le jeton fourni, selon SECURITY.md. Avec un administrateur, cela inclut des opérations d’administration ; le mode lecture seule, la désactivation d’outils et les politiques d’approbation limitent ce périmètre.

Le projet envoie-t-il des données à son auteur ?

Selon PRIVACY.md (juin 2026), aucune télémétrie n’est collectée ; les rapports de bogue ne partent qu’avec votre accord. Vos données sont en revanche traitées par le client IA que vous connectez.

Conclusion

ha-mcp montre ce que devient un agent quand on lui confie un système réel : l’essentiel de la sécurité tient aux droits du jeton, au secret de l’URL et aux garde-fous d’approbation. Traitez-le comme un composant à restreindre dès le premier jour. Sources : dépôt homeassistant-ai/ha-mcp (README, SECURITY.md, docs/FAQ.md, LICENSE), lues le 27 octobre 2026.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC, ni à Home Assistant, ni aux auteurs de ha-mcp ni aux projets cités. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
CLAUDE.md Karpathy : mesurer l'effet sur un agent de code

CLAUDE.md Karpathy : mesurer l’effet sur un agent de code

Next Post
Dynatrace Assist agentique : ce qu'il fait, ce qu'il ne fait pas

Dynatrace Assist agentique : ce qu’il fait, ce qu’il ne fait pas

Related Posts