ha-mcp : piloter Home Assistant avec Claude ou ChatGPT

ha-mcp est un serveur MCP open source qui relie un assistant IA comme Claude ou ChatGPT à Home Assistant. Il expose 87 outils : l’assistant peut créer des automatisations, modifier un tableau de bord ou chercher pourquoi un scénario ne fonctionne pas, à partir d’une simple conversation. Cet article explique comment il fonctionne, comment l’installer et ce qu’il faut savoir avant de lui confier ta maison.

En bref

• Serveur MCP sous licence MIT, écrit à 97 % en Python
• 87 outils pour chercher, piloter, configurer et surveiller Home Assistant
• Installation recommandée via HACS, ou le Marketplace à partir de Home Assistant 2026.11
• Une URL à coller dans le client IA ; plus de 15 clients pris en charge
• Mode lecture seule et sauvegardes automatiques des modifications

Qu’est-ce que ha-mcp ?

Home Assistant est un logiciel de domotique libre. Le configurer oblige souvent à écrire à la main des automatisations, des scripts et des tableaux de bord. ha-mcp confie ce travail à un assistant IA : tu décris ce que tu veux, et l’assistant agit sur ton installation.

Le projet suit le protocole MCP (Model Context Protocol), qui permet à un assistant IA d’utiliser des outils externes. Il est construit avec FastMCP, publié sous licence MIT, et fonctionne avec Claude, ChatGPT, Cursor, Copilot et plus de 15 clients, selon sa documentation.

Ce que ha-mcp permet de faire

Le README donne des exemples de phrases à dire à l’assistant. Il peut créer une automatisation qui allume la lumière du porche au coucher du soleil, ajouter une carte météo à un tableau de bord, ou créer un script « mode film » qui baisse les lumières, ferme les volets et allume la télévision.

Il sait aussi corriger l’existant : pour une automatisation qui ne marche pas, il analyse les traces d’exécution, repère le problème et propose des corrections. Les 87 outils sont rangés en grandes familles.

• Recherche : entités (recherche approximative), configuration en profondeur, vue d’ensemble du système
• Contrôle : n’importe quel service, pilotage groupé d’appareils, états en temps réel
• Gestion : automatisations, scripts, helpers, tableaux de bord, pièces, zones, groupes, calendriers, blueprints
• Suivi : historique, statistiques, captures de caméra, traces d’automatisations, appareils ZHA
• Système : sauvegarde et restauration, mises à jour, apps (add-ons), registre des appareils

Comment fonctionne ha-mcp

La méthode recommandée est une intégration qui s’installe dans Home Assistant et fait tourner le serveur complet à l’intérieur de celui-ci. Elle convient à tous les types d’installation : Home Assistant OS, Supervised, Container et Core. Le serveur agit avec les droits d’un compte administrateur, via un jeton d’accès.

Le README propose deux options : créer un jeton longue durée sur ton propre compte, ou, plus sûr selon lui, créer un compte dédié à ha-mcp, limité à l’accès local et administrateur. L’assistant se connecte ensuite à une URL, soit un webhook pour l’accès à distance (via Nabu Casa ou un reverse proxy), soit une adresse directe sur le réseau local.

Installer ha-mcp dans Home Assistant

Il faut Home Assistant 2026.8.0 ou plus récent. Sur les versions 2026.8 à 2026.10, ouvre HACS, cherche HA-MCP et télécharge-le. À partir de la 2026.11, passe par Paramètres, Marketplace, puis Installer. Redémarre ensuite Home Assistant.

Va dans Paramètres, Appareils et services, Ajouter une intégration, puis choisis HA-MCP Server. Colle ton jeton (ou l’identifiant et le mot de passe du compte dédié), choisis le mode de connexion et valide. L’accès à distance et l’accès réseau local sont tous deux désactivés au départ : un client sur un autre appareil a besoin de l’un des deux.

Copie ensuite l’URL affichée dans l’écran Configurer de l’intégration et colle-la dans ton client IA. Un assistant de configuration en ligne génère la configuration propre à chaque client. Le projet signale qu’il faut choisir une seule méthode d’installation par client : deux entrées pour le même serveur provoquent des blocages de connexion.

Essayer ha-mcp avec le serveur de démonstration

Pour tester sans toucher à ta maison, le projet fournit des scripts d’installation qui connectent Claude Desktop à un environnement de démonstration hébergé, sans abonnement payant. Sur macOS, la commande est la suivante, après connexion à un compte claude.ai.

Il existe des scripts équivalents pour Linux et Windows. Une fois Claude Desktop relancé, le README propose de demander : « Can you see my Home Assistant? ». Ce mode utilise la connexion stdio, que le projet déconseille pour un usage réel à cause de problèmes de transport connus.

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

Autres méthodes et sécurité

Si tu préfères une app (add-on) sur Home Assistant OS ou Supervised, c’est la deuxième option du projet : aucun jeton à gérer. Pour les installations Container ou Core, ou un autre hôte, le serveur existe aussi en Docker et via PyPI avec uvx. Une authentification OIDC peut protéger l’accès distant.

Côté garde-fous, le README cite un interrupteur de mode lecture seule, l’activation ou la désactivation outil par outil, des politiques de sécurité demandant l’approbation de l’utilisateur et des sauvegardes automatiques avant modification. Un panneau d’administration HA-MCP apparaît dans la barre latérale de Home Assistant pour régler ces options.

Où en est le projet

Le dépôt a été créé le 14 septembre 2025. Au 12 novembre 2026, il compte 7 570 étoiles, 459 copies, 104 contributeurs et 20 tickets et demandes de fusion ouverts. Son code a été modifié le jour même.

Les dernières préversions de la 9.3.0 ddataient des 11 et 12 novembre 2026. L’une d’elles fait reposer l’outil de traces d’automatisations sur les données de trace du cœur de Home Assistant. Le README signale aussi un changement incompatible depuis la 7.3.0 : l’outil ha_config_set_yaml est passé en bêta.

Quelques repères

• MCP : Le Model Context Protocol est un standard ouvert qui permet à un assistant IA de se connecter à des outils et à des services externes pour les consulter ou agir dessus.
• Jeton d’accès longue durée : C’est une clé secrète qui permet à un programme de s’identifier auprès d’un service sans mot de passe. Si elle fuite, quiconque la possède peut agir à la place de son propriétaire.
• Webhook : Un webhook est une adresse web qu’un service expose pour recevoir des messages d’un autre programme. Elle sert ici de point d’entrée pour une connexion à distance.

Questions fréquentes

ha-mcp est-il gratuit ?

Oui, ha-mcp est publié sous licence MIT. Un compte Claude gratuit suffit pour l’utiliser avec Claude Desktop, avec des limites d’usage sur les comptes gratuits.

Faut-il un abonnement Claude Pro pour utiliser ha-mcp ?

Non. La FAQ du projet précise que Claude Desktop fonctionne avec un compte gratuit, et que d’autres clients IA sont pris en charge (plus de 15).

Quelle version de Home Assistant faut-il pour installer ha-mcp ?

Il faut Home Assistant 2026.8.0 ou plus récent pour l’intégration. Jusqu’à la 2026.10 on passe par HACS ; à partir de la 2026.11, par le Marketplace.

Quelle différence entre ha-mcp et le MCP intégré à Home Assistant ?

Selon la FAQ du projet, le MCP intégré compte une quinzaine d’outils de base centrés sur le contrôle des appareils. ha-mcp en propose 87 et vise l’administration complète : automatisations, tableaux de bord, caméras.

À retenir

ha-mcp donne à Claude, ChatGPT et d’autres assistants IA 87 outils pour configurer, piloter et surveiller Home Assistant, avec un mode lecture seule et des sauvegardes automatiques. L’installation recommandée passe par HACS ou le Marketplace, et se termine par une URL à coller dans le client IA.