ha-mcp : Home Assistant + MCP pour agents IA

Home Assistant a bien sa propre intégration MCP officielle, mais elle se limite aux entités exposées à Assist et ne sait ni créer une automatisation, ni éditer un dashboard, ni déboguer une trace d’exécution. ha-mcp comble ce trou : un serveur MCP tiers qui donne à un agent IA un accès quasi complet à la configuration de Home Assistant, pas seulement à ses capteurs.

Ce que fait ha-mcp

ha-mcp (nom complet du dépôt : “The Unofficial and Awesome Home Assistant MCP Server”) est un serveur Model Context Protocol écrit en Python avec le framework FastMCP. Il expose 88 outils organisés par catégorie : contrôle de services et d’appareils, gestion des automatisations/scripts/scènes, dashboards Lovelace, zones/aires/étages, helpers, calendriers, todo-lists, historique et statistiques, sauvegardes, mises à jour, apps (add-ons), HACS, registre des appareils et entités, etc.

Concrètement, un client MCP (Claude Desktop, Claude Code, claude.ai, ChatGPT, Gemini CLI, Cursor, VSCode, Open WebUI et une quinzaine d’autres clients supportés) peut demander en langage naturel des choses comme :

“Crée une automatisation qui allume la lumière du porche au coucher du soleil”
“Mon automatisation de détection de mouvement ne marche pas, débogue-la”
“Ajoute une carte météo à mon dashboard”

Le serveur traduit la demande en appels d’outils MCP concrets (lecture d’état, appel de service, écriture de config YAML, etc.).

Projet dépôt GitHub : ~4,5k étoiles, licence MIT, créé en septembre 2025, activité de commits continue (dernier push le jour de la rédaction de cet article). Maintenu par une petite équipe de contributeurs (@julienld, créateur ; @sergeykad, @kingpanther13, @Patch76, mainteneurs) — projet communautaire, non affilié à Nabu Casa / Home Assistant.

Installation

Le README distingue plusieurs méthodes ; le projet insiste pour n’en garder qu’une seule active à la fois (faire tourner deux méthodes en parallèle pour le même client MCP provoque des blocages de connexion documentés).

Méthode recommandée : composant personnalisé via HACS

Tourne en process dans Home Assistant, fonctionne sur tous les types d’installation (OS, Supervised, Container, Core), sans jeton d’accès à gérer :

Dans HACS : Integrations → ⋮ → Custom repositories, ajouter https://github.com/homeassistant-ai/ha-mcp-integration (catégorie Integration), puis Download.
Redémarrer Home Assistant.
Settings → Devices & Services → Add Integration, rechercher HA-MCP Custom Component, choisir HA-MCP Server, Submit.
Récupérer l’URL de connexion dans l’écran Configure de l’intégration (ou dans les logs Home Assistant).
Coller cette URL dans le client IA.

Installation manuelle possible sans HACS en copiant custom_components/ha_mcp_tools/ du dépôt dans config/custom_components/.

App (add-on) — OS et Supervised

Settings → Apps → Install app → ⋮ → Repositories
→ ajouter https://github.com/homeassistant-ai/ha-mcp

Puis installer “Home Assistant MCP Server” et cliquer Start. L’URL MCP unique apparaît dans l’onglet Logs, sans jeton à configurer.

Méthodes externes (Container / Core / hôte séparé)

# Docker, mode serveur HTTP
docker run ghcr.io/homeassistant-ai/ha-mcp
# nécessite HOMEASSISTANT_URL et HOMEASSISTANT_TOKEN (jeton longue durée HA)

# PyPI / uvx, même principe en HTTP streamable
uvx ha-mcp@latest

Le Setup Wizard officiel génère la configuration exacte à coller côté client pour chacune de ces méthodes — je ne l’ai pas reproduite ici pour éviter d’indiquer un format de config obsolète.

Démo rapide (sans votre propre Home Assistant)

Scripts one-liner pour tester contre une instance de démo hébergée, en connexion stdio locale :

# macOS
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh

# Linux
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex

Le README prévient que le transport stdio a des problèmes de connexion connus — recommandé seulement pour tester, pas pour un usage réel (préférer le composant HACS ou une méthode HTTP).

Garde-fous et sécurité

Vu l’étendue des permissions (création/suppression d’automatisations, édition de dashboards, restauration de sauvegardes, écriture de fichiers YAML en bêta), ha-mcp embarque plusieurs mécanismes de contrôle :

Read Only Mode — bascule globale qui interdit toute écriture.
Activation/désactivation par outil — désactiver individuellement les outils sensibles (suppression, écriture YAML, etc.).
Tool security policies — règles d’approbation par outil, avec validation utilisateur avant exécution.
Sauvegardes automatiques avant certaines éditions de configuration.
Un mode de découverte par recherche (ENABLE_TOOL_SEARCH) pour les petits modèles ou les clients qui chargent tout le catalogue d’outils d’un coup (utile pour ne pas saturer le contexte d’un modèle local).

Les outils de lecture/écriture de fichiers et d’édition YAML (ha_config_set_yaml, ha_read_file, ha_write_file, etc.) sont encore en bêta, désactivés par défaut, et nécessitent le composant personnalisé plus des feature flags dédiés.

+ Les points forts

Couverture large — 88 outils qui vont bien au-delà du contrôle d’appareils : création d’automatisations, dashboards, helpers, zones, sauvegardes, HACS, registre d’appareils
Zéro jeton à gérer avec l’installation recommandée (composant HACS en process)
Multi-client — Claude Desktop, Claude.ai, Claude Code, ChatGPT, Gemini CLI, Cursor, VSCode, Open WebUI, 15+ clients au total, avec un assistant de configuration dédié par client
Local et transparent sur la vie privée — tourne sur le réseau local, pas de télémétrie à ce jour
Projet actif — commits réguliers, releases de développement (.devN) à chaque push sur master, communauté de contributeurs qui grandit
Skills complémentaires — le dépôt homeassistant-ai/skills apporte des bonnes pratiques Home Assistant (choix du bon type de helper, structuration des automatisations) pour éviter que l’agent ne bricole des solutions bancales

- Les points faibles

Projet non officiel — pas affilié à Nabu Casa/Home Assistant, maintenu par des bénévoles ; à évaluer avant de lui donner un accès en écriture à une configuration de production
Fonctions YAML/fichiers encore bêta — les outils les plus sensibles (écriture de configuration.yaml, accès fichiers) ne sont pas encore stables
Transport stdio buggé — problème de connexion documenté, contournable seulement en passant par le composant HACS ou une méthode HTTP
Configuration multi-méthodes piégeuse — le README avertit explicitement qu’exécuter deux installations du serveur en parallèle pour un même client casse la connexion
Risque inhérent au langage naturel sur une config critique — un agent qui peut créer, modifier ou supprimer des automatisations et des sauvegardes peut aussi se tromper ; les garde-fous (Read Only Mode, approbations par outil) réduisent le risque mais ne l’éliminent pas
ChatGPT derrière un pare-feu demande un montage supplémentaire (tunnel communautaire tiers) car les connecteurs ChatGPT exigent une URL publiquement joignable

ha-mcp vs l’intégration MCP Server officielle de Home Assistant

Home Assistant fournit sa propre intégration MCP Server, basée sur le pipeline Assist. Elle expose les intents Assist déjà configurés (utile pour du contrôle façon commande vocale), mais rien de plus.

	Intégration MCP officielle	ha-mcp
Contrôler les appareils exposés	✅	✅
Portée des entités	Seulement celles exposées à Assist	Toutes les entités Home Assistant
Créer/éditer automatisations, scripts, scènes	❌	✅
Construire/éditer des dashboards	❌	✅
Déboguer via traces, historique, logs	❌	✅
Gérer helpers, aires, zones, labels, groupes	❌	✅
Sauvegardes, apps, HACS, registre appareils/entités	❌	✅
Statut	Officiel, intégré au core HA	Communautaire, tiers

En résumé : l’intégration officielle suffit pour du contrôle vocal simple sur des entités déjà exposées. ha-mcp vise un usage plus large — un agent qui construit et maintient la configuration, pas seulement qui l’actionne.

En résumé

ha-mcp transforme un agent IA en véritable copilote de configuration Home Assistant, pas juste en télécommande vocale. C’est un vrai plus pour créer et déboguer des automatisations en langage naturel, au prix d’un accès en écriture large qu’il faut cadrer avec les garde-fous fournis (Read Only Mode, approbations par outil). Pour du contrôle vocal basique sur quelques entités déjà exposées à Assist, l’intégration officielle de Home Assistant reste plus simple et suffisante.

Voir aussi :

1Panel — un autre outil d’administration self-hosted avec assistant IA compatible MCP
Tailscale — exposer une instance Home Assistant à un client MCP distant sans ouvrir de port