Home Assistant MCP Server

À propos

Résumé automatique de la documentation et de la configuration de homeassistant-ai/ha-mcp, traduit automatiquement. Une erreur, ou tu maintiens ce projet et tu veux ton propre texte ici ? Prendre contact

Prise en charge

• S’ouvre dans la barre latérale Sa propre page s’ouvre dans Home Assistant.

• Maintenance active Son auteur a publié une version ou poussé une modification au cours des six derniers mois.

Mise en place

Ajoute son dépôt d’applications dans Paramètres > Applications, puis installe-la et démarre-la.

Extrait de la documentation

Autorisations

• Réseau de l’hôteUtilise directement le réseau de l’hôte au lieu du sien.
• API Home AssistantPeut lire et contrôler Home Assistant.
• API SupervisorPeut communiquer avec le Supervisor, qui gère les applications et le système.

Réseau

• 9583/tcp

Configuration

• Vérifier les certificats TLSVérifie le certificat TLS du serveur Home Assistant. Ne désactivez cette option que sur un réseau de confiance, pour un certificat auto-signé ou une non-correspondance de nom d'hôte : cela affaiblit la sécurité du transport.
• Concurrence des outils Home AssistantLimite facultative sur les appels d'outils Home Assistant externes pour toutes les sessions. La concurrence interne pour REST, WebSocket et la répartition par outil reste inchangée. 0 conserve un comportement illimité. Un appel en attente de capacité échoue après 60 secondes. Plage 0–32.
• Niveau d'indication de sauvegardeAvec quelle insistance il est demandé aux assistants IA de suggérer une sauvegarde complète de Home Assistant avant des modifications risquées. Cela ne modifie que cette indication ; les sauvegardes automatiques de modification ont leur propre paramètre.
• Instructions personnalisées du serveurTexte envoyé à chaque assistant IA qui se connecte, dans le cadre des instructions du serveur MCP — par exemple, l'emplacement des notes du foyer et le moment de les lire ou de les mettre à jour. Fait également partie du prompt des agents de conversation Home Assistant (Assist) qui utilisent cet ensemble d'outils. Utilisez-le pour fournir des directives destinées à tous vos clients en même temps ; restez concis et évitez d'y inclure des secrets. Laissez vide pour ne rien ajouter. Nécessite un redémarrage ; les clients voient le changement lorsqu'ils se reconnectent.
• Activer la recherche d'outilsRemplacer le catalogue complet d'outils par une découverte basée sur la recherche. Réduit le contexte inactif d'environ 90 %, à environ 5K jetons. ⚠️ N'activez PAS cette option dans les clients disposant de leur propre recherche d'outils intégrée / d'outils différés (claude.ai, Claude Desktop, Claude Code) — les deux couches de recherche entrent en conflit, et la recherche d'outils intégrée du client constitue le meilleur choix dans ce cas ; laissez cette option désactivée. Le fait que les outils soient différés dépend de votre association client et modèle : utilisez cette option lorsque votre configuration charge le catalogue complet au départ — modèles sans outils différés natifs (par ex. Gemini, modèles locaux compatibles OpenAI, Claude Haiku), clients qui intègrent tous les schémas d'outils quel que soit le modèle (par ex. GitHub Copilot CLI), ou fenêtres de contexte plus petites. Certains modèles Codex et ChatGPT incluent également des outils différés — vérifiez directement votre client/modèle pour confirmer ses fonctionnalités afin de ne pas laisser cette option activée inutilement. Les outils sont trouvés via ha_search_tools et exécutés via des proxys catégorisés (lecture/écriture/suppression). Nécessite un redémarrage de l'application (add-on) pour prendre effet — puis reconnectez ou actualisez le serveur MCP dans votre client IA afin qu'il recharge la liste des outils. Le seul redémarrage de l'application (add-on) ne met PAS à jour la liste des outils mise en cache par un client ; cela s'applique après la modification de n'importe quel paramètre ici.
• Résultats max. de la recherche d'outilsNombre maximal d'outils cachés renvoyés par appel à ha_search_tools lorsque la recherche d'outils est activée ; un outil épinglé qui se classe dans ce nombre de tête est ajouté en tant qu'entrée courte avec uniquement son nom par-dessus. Des valeurs plus faibles (2-3) économisent les jetons de contexte mais peuvent manquer des outils pertinents. Redémarrage requis. Plage 2–10.
• Activer les politiques de sécurité des outils (avancé)Contrôle les appels d'outils à enjeux élevés (contrôle des serrures/alarmes, écritures d'automatisations, etc.) derrière une approbation utilisateur. Lorsqu'un outil protégé est appelé, l'agent dit à l'utilisateur d'ouvrir l'onglet Politiques de sécurité des outils dans l'interface Web et de cliquer sur Approuver avant que l'appel ne continue. Les règles par outil avec conditions d'argument optionnelles sont configurées dans l'onglet Politiques de sécurité des outils. Désactivé par défaut. Nécessite un redémarrage pour prendre effet.
• Permettre aux agents IA de modifier les politiques de sécurité des outilsEnregistre l'outil ha_manage_security_policy, qui permet aux agents IA connectés de lire et de réécrire les politiques de sécurité des outils — y compris la suppression des portes d'approbation. Désactivé par défaut. Indépendant de l'option Politiques de sécurité des outils ci-dessus : ceci contrôle qui peut modifier les règles, et non si elles sont appliquées. L'outil ne peut pas voir ou décider des approbations en attente. Pour garder un humain dans la boucle, soumettez l'outil à une approbation avant de l'activer : activez « soumis à la sécurité » pour Gérer la politique de sécurité dans l'onglet Outils de l'interface web. Nécessite un redémarrage pour prendre effet.
• Mode lecture seuleDésactive tous les outils d'écriture et supprime la capacité des outils d'effectuer des appels d'écriture ou destructifs. Les outils mixtes lecture/écriture — sauvegardes, applications (add-ons), préférences énergétiques, pipelines vocaux et mode code lorsqu'il est activé — restent disponibles avec leurs opérations d'écriture bloquées. Même interrupteur que l'onglet Outils de l'interface Web. Désactivé par défaut. Nécessite un redémarrage pour prendre effet.
• Masquer les secretsMasque les secrets dans les réponses des outils avant qu'ils n'atteignent l'assistant IA. Les options de l'application (add-on) et les champs d'intégration marqués comme mots de passe sont remplacés par un marqueur défini/vide (afin que la question « ce identifiant est-il configuré ? » reste traitable), et les autres réponses d'outils sont nettoyées des valeurs secrètes déjà vues par le serveur (les valeurs de moins de 6 caractères sont ignorées, car le remplacement de minuscules fragments corromprait des sorties sans rapport). Les autres champs ne sont pas détectés, à l'exception des clés privées dans les options de l'application et des noms d'options d'application listés ci-dessous. Désactivé par défaut.
• Clés d'options d'application supplémentaires à masquerNoms d'options de l'application (add-on) à masquer comme les champs de mot de passe, pour les applications dont le schéma stocke un secret en texte brut (par exemple backup_password). Séparez les noms par des virgules ou des retours à la ligne. Un nom s'applique à toutes les applications ; écrivez app_slug:name pour le limiter à une seule application. Nommer un groupe d'options couvre toutes les options qu'il contient. Utilisé uniquement lorsque l'option Masquer les secrets est active. Vide par défaut.
• Attacher les compétences de bonnes pratiques aux écrituresInterrupteur principal pour la fonction de livraison de contenu de compétences d'outils d'écriture (problème #1182). Lorsqu'il est activé (par défaut), les six outils d'écriture de configuration (automatisations, scripts, scènes, assistants, tableaux de bord, YAML brut) attachent les fichiers de référence canoniques des bonnes pratiques Home Assistant sous skill_content à chaque écriture réussie, plus l'intégration automatique de toutes les sections de référence citées par les avertissements de bonnes pratiques. Chaque outil expose également un paramètre MandatoryBPS par appel que l'agent peut définir sur false lors des appels suivants une fois qu'il a le contenu. Lorsque cet interrupteur principal est désactivé, AUCUN skill_content n'est émis, indépendamment du paramètre par appel ou des avertissements BP. Recommandé ACTIVÉ comme premier choix ; désactivez uniquement pour les modèles avec de très petites fenêtres de contexte. Désactiver ceci peut dégrader la précision des écritures. Nécessite un redémarrage pour prendre effet.
• Mode strict de bonnes pratiquesMode strict : empêche le client d'utiliser l'outil jusqu'à ce qu'il puisse prouver qu'il a lu les bonnes pratiques. Lorsqu'il est activé, les six outils d'écriture de bonnes pratiques (automatisations, scripts, scènes, assistants, tableaux de bord, YAML brut) sont bloqués et renvoient une erreur dirigeant le client vers la compétence de bonnes pratiques via ha_get_skill_guide et lui demandant de renvoyer la clé d'accusé de réception obtenue. Lorsqu'il est activé, l'outil ha_get_skill_guide est verrouillé activé — il est le seul éditeur de la clé d'accusé de réception. Enfant de l'option « Attacher les compétences de bonnes pratiques aux écritures » ci-dessus et inerte lorsque ce parent est désactivé. Nécessite un redémarrage pour prendre effet.
• Sauvegardes automatiques des modificationsEnregistre un instantané d'une entité avant que chaque appel d'outil d'écriture ou de suppression ne la modifie. Tant que cette option est désactivée, les outils de fichiers et de YAML brut (ha_write_file, ha_delete_file, ha_config_set_yaml) refusent d'écrire.
• Limitation de la sauvegarde automatique (minutes)Fréquence à laquelle la sauvegarde automatique peut capturer la même entité. 0 capture à chaque écriture ; N supérieur à 0 capture au maximum un instantané par N minutes et par entité. Plage 0–1440.