Home Assistant et MCP : créer avec Claude, Codex et ChatGPT

MCP relie l'IA à la maison, mais ne remplace pas Home Assistant

Le serveur MCP natif de Home Assistant permet à Claude, Codex ou ChatGPT de lire le contexte en temps réel et d'utiliser les outils de l'API Assist sur les entités explicitement exposées. Il aide à inventorier les entity_id, comprendre un état et tester une commande. Il n'est pas un éditeur général : il ne faut pas présumer qu'il peut écrire automations.yaml, modifier un dashboard ou administrer toutes les intégrations.

Le flux fiable est observation, proposition, validation humaine, puis enregistrement dans Home Assistant. L'automatisation finale s'exécute localement sans appeler l'IA à chaque déclenchement. Une panne Internet ou une limite de forfait ne doit pas bloquer une alerte de fuite ou l'éclairage d'une pièce.

• Home Assistant — serveur Model Context Protocol ↗
• Home Assistant — intégration cliente MCP ↗

Choisir le client et le transport

Home Assistant expose /api/mcp en Streamable HTTP. Codex prend en charge stdio et Streamable HTTP; Claude Code recommande HTTP pour un serveur distant. ChatGPT Web utilise une application ou un plugin MCP distant et ne lit pas la configuration locale de Codex. La disponibilité dépend aussi du forfait et des politiques de l'espace de travail.

Le serveur MCP rend Home Assistant accessible à un client IA. L'intégration cliente MCP fait l'inverse : elle permet à un agent de conversation dans Home Assistant d'utiliser les outils d'un serveur MCP externe.

• OpenAI — MCP avec ChatGPT et Codex ↗
• OpenAI — connecter un plugin MCP ↗
• Anthropic — MCP dans Claude Code ↗

1. Préparer Home Assistant avec le moindre privilège

La page des entités exposées est la frontière essentielle. /api/mcp/assist force l'API Assist; une autre API LLM exige un utilisateur administrateur.

• Créer une sauvegarde et confirmer qu'elle peut être restaurée.
• Inventorier les entity_id et états bruts dans Outils pour développeurs > États.
• Ajouter Model Context Protocol Server dans Appareils et services.
• Exposer seulement les capteurs et actionneurs nécessaires à Assist.
• Utiliser un compte distinct non administrateur pour /api/mcp/assist quand possible.
• Exclure au départ serrures, garage, alarmes, vanne principale et scripts sensibles.

• Home Assistant — exposer des entités à Assist ↗
• Home Assistant — sauvegardes ↗

2. Configurer Claude, Codex ou ChatGPT

Sur Home Assistant OS comme sur Container, le serveur natif s'ajoute par l'interface et n'exige pas d'add-on. Un proxy local tourne généralement sur le poste client; avec Container, il peut aussi être isolé dans un conteneur. Ne placez jamais un jeton dans une image, Git ou un fichier partagé.

Claude Desktop peut utiliser mcp-proxy et un jeton longue durée sur le LAN. Claude Code et Codex peuvent utiliser OAuth directement contre une URL locale. ChatGPT exige une URL HTTPS joignable à distance : Home Assistant Cloud simplifie ce cas; un tunnel exige une URL externe et des en-têtes transférés cohérents.

mcp_oauth_callback_port = 12345

[mcp_servers.homeassistant]
url = "https://ha.example.net/api/mcp/assist"
auth = "oauth"
oauth = { client_id = "http://127.0.0.1:12345" }

# Puis : codex mcp login homeassistant

claude mcp add-json "HA" '{
  "type": "http",
  "url": "https://ha.example.net/api/mcp/assist",
  "oauth": {"clientId": "http://localhost:12345", "callbackPort": 12345}
}' --client-secret

• Article — Cloudflare Tunnel sur Unraid →
• Home Assistant — authentification de l'API ↗

3. Protéger OAuth, les jetons et l'accès distant

Préférez OAuth. Home Assistant utilise un document de métadonnées de Client ID plutôt que l'enregistrement dynamique RFC 7591. Le Client ID est https://claude.ai pour le connecteur Claude distant et https://chatgpt.com pour ChatGPT; ce n'est jamais l'URL Home Assistant.

Un jeton longue durée reste puissant jusqu'à révocation. Stockez-le dans un gestionnaire de secrets ou une variable d'environnement. Avec un tunnel, le nom d'hôte doit correspondre exactement à l'URL externe et le proxy doit transmettre les bons en-têtes.

• TLS valide, URL canonique unique et MFA.
• Aucun secret dans les prompts, YAML ou dépôts.
• Confirmation humaine pour toute écriture sensible.
• Journalisation et procédure de révocation testée.

4. Observer avant d'autoriser les commandes

Commencez par lister les entités exposées, lire l'état d'une pièce et expliquer une automatisation. Testez ensuite une commande réversible sur une lampe. Une réponse textuelle ne prouve pas l'appel d'un outil : contrôlez le journal du client et l'état Home Assistant.

Lis uniquement le contexte Home Assistant exposé. Liste les entity_id de présence, luminosité, énergie et température. Signale les entités absentes ou unavailable. Ne commande aucun appareil et ne modifie aucune configuration.

Exemple 1 — éclairage selon présence et luminosité

Ce brouillon fonctionne localement après son enregistrement dans Home Assistant. Remplacez les entity_id et le seuil après avoir observé le capteur réel. Les déclencheurs lancent l'évaluation; les conditions exigent ensuite présence et faible luminosité.

- id: bureau_eclairage_presence_lux
  alias: Bureau - éclairage selon présence et luminosité
  triggers:
    - trigger: state
      entity_id: binary_sensor.bureau_presence
      to: "on"
      id: presence
    - trigger: numeric_state
      entity_id: sensor.bureau_illuminance
      below: 80
      id: sombre
    - trigger: state
      entity_id: binary_sensor.bureau_presence
      to: "off"
      for: "00:05:00"
      id: absence
  actions:
    - choose:
        - conditions:
            - condition: template
              value_template: "{{ trigger.id in ['presence', 'sombre'] }}"
            - condition: state
              entity_id: binary_sensor.bureau_presence
              state: "on"
            - condition: numeric_state
              entity_id: sensor.bureau_illuminance
              below: 80
          sequence:
            - action: light.turn_on
              target:
                entity_id: light.bureau_plafond
        - conditions:
            - condition: template
              value_template: "{{ trigger.id == 'absence' }}"
          sequence:
            - action: light.turn_off
              target:
                entity_id: light.bureau_plafond
  mode: restart

• Home Assistant — automations en YAML ↗

Exemple 2 — alerte de fuite d'eau sans action irréversible

Une alerte de fuite doit continuer à fonctionner sans IA. La fermeture automatique d'une vanne exige des essais du sens d'action, de l'alimentation, de l'état unavailable et du contournement manuel; cet exemple se limite donc à alerter.

- id: sous_sol_alerte_fuite
  alias: Sous-sol - alerte fuite d'eau
  triggers:
    - trigger: state
      entity_id: binary_sensor.sous_sol_fuite_eau
      to: "on"
  actions:
    - action: persistent_notification.create
      data:
        title: "Fuite d'eau détectée"
        message: "Vérifier le capteur du sous-sol immédiatement."
    - action: notify.mobile_app_telephone_marc
      data:
        title: "Alerte Home Assistant"
        message: "Fuite d'eau détectée au sous-sol."
  mode: single

Révise ce brouillon sans l'appliquer. Confirme les états bruts, le service notify, les cas unavailable et la trace attendue. Ne ferme aucune vanne et ne désactive aucune alarme.

Exemple 3 — dashboard énergie, température et présence

Un dashboard créé dans l'interface est normalement stocké par Home Assistant; un dashboard YAML reste un fichier géré séparément. N'écrasez pas le stockage interne avec un outil externe. Commencez avec des cartes natives avant d'ajouter une dépendance HACS.

title: Maison
views:
  - title: Vue d'ensemble
    path: accueil
    cards:
      - type: entities
        title: Présence
        entities:
          - binary_sensor.bureau_presence
          - person.marc
      - type: gauge
        entity: sensor.consommation_maison_w
        name: Puissance actuelle
        min: 0
        max: 10000
        severity:
          green: 0
          yellow: 4000
          red: 7000
      - type: history-graph
        title: Température - 24 h
        hours_to_show: 24
        entities:
          - sensor.salon_temperature
          - sensor.sous_sol_temperature

• Home Assistant — tableaux de bord ↗
• Article — Home Assistant, Matter et Thread →

8. Enregistrer, valider et tester

Les traces exigent un id pour le YAML et Home Assistant en conserve cinq par défaut. Un numeric_state réagit au franchissement du seuil, pas au simple fait que la valeur soit déjà sous le seuil.

• Coller le brouillon avec Modifier en YAML, enregistrer, puis rouvrir l'automatisation.
• Garder un id unique; automations.yaml doit rester une liste et ne doit pas être modifié simultanément par l'UI et à la main.
• Exécuter la vérification de configuration dans Outils pour développeurs > YAML.
• Tester conditions et actions, puis provoquer un vrai changement d'état.
• Lire la trace : déclencheur, conditions, branche choose, service et erreur.
• Surveiller unavailable, doubles déclenchements et le mode d'exécution.

• Home Assistant — dépannage des automatisations ↗

9. Retour arrière et gouvernance

Un serveur MCP communautaire offrant l'écriture directe ou de nombreux outils d'administration élargit le risque. Vérifiez dépôt primaire, version, outils annoncés, annotations lecture/écriture et authentification; isolez-le et gardez une approbation humaine. MCP n'est pas une garantie de sécurité.

• Nommer la sauvegarde et noter la version Home Assistant.
• Versionner les fichiers gérés manuellement sans secrets.
• Désactiver avant de supprimer et conserver la trace d'erreur.
• Révoquer OAuth ou le jeton, retirer l'application MCP et réduire les entités exposées.
• Documenter qui approuve les actions sensibles.

Dépannage rapide

Une intégration fiable reste locale à l'exécution

Claude, Codex et ChatGPT accélèrent l'inventaire, la rédaction et la revue lorsque MCP leur donne un contexte réel. La qualité vient des limites : entités minimales, authentification adaptée, brouillon plutôt qu'écriture aveugle, validation Home Assistant et retour arrière testé.

Ce guide fournit une méthode et des exemples fictifs; il ne remplace pas une revue de sécurité et de fiabilité d'une installation complexe.

• Service — Intégration d'agents IA et serveurs MCP →
• Service — Solutions résidentielles →