Home Assistant Admin MCP

Un servidor de Model Context Protocol (MCP) orientado a la seguridad para inspeccionar, controlar, diagnosticar y administrar selectivamente una instancia de Home Assistant. Combina las API REST y WebSocket de Home Assistant con un montaje de configuración de Home Assistant opcional y restringido.

El servidor no incluye un LLM. Un cliente MCP elige las herramientas; este servidor valida la entrada, aplica la política de despliegue, se comunica con Home Assistant y devuelve resultados estructurados.

[!NOTE] Este proyecto se ha creado con herramientas de desarrollo asistidas por IA.

[!WARNING] El modo admin puede cambiar dispositivos, registros, asistentes, automatizaciones, scripts, escenas, integraciones y configuración YAML, y puede reiniciar Home Assistant. Comience en read_only, use una cuenta de Home Assistant dedicada, revise las ejecuciones de prueba y exponga el endpoint HTTP solo a clientes de confianza.

Alcance y límites

Las capacidades implementadas incluyen:

• Inspección del estado en tiempo de ejecución, servicios/acciones, eventos, historial, logbook, estadísticas y registros de la sesión actual con respaldo condensado de system_log.

• Descubrimiento de registros e integraciones con áreas, dispositivos, entidades y entradas de configuración vinculados entre sí.

• Llamadas a servicios validadas con objetivos explícitos y definiciones de servicios de Home Assistant en vivo.

• Lecturas y mutaciones de automatizaciones, scripts y escenas gestionadas por el editor.

• Mutaciones de asistentes respaldadas por almacenamiento y de registros/entradas de configuración seleccionados a través de las API internas de Home Assistant.

• Diagnósticos, análisis de dependencias, búsquedas en registros/recursos del editor/YAML en la lista blanca, trazas, diferencias de configuración, puntos de control e historial de Git acotado.

• Parches YAML estructurales bajo una lista blanca de sistema de archivos explícita.

Objetivos excluidos y limitaciones explícitos:

• Sin API de Supervisor de Home Assistant, gestión de add-ons, gestión del host ni API de copias de seguridad de Home Assistant.

• Sin API de Docker, socket de Docker, ciclo de vida de contenedores, gestión de imágenes ni acceso a los registros de contenedores. El despliegue no monta /var/run/docker.sock.

• Sin ejecución arbitraria de shell ni acceso arbitrario al sistema de archivos.

• Sin implementación genérica de config-flow/options-flow ni mecanismo para enviar credenciales arbitrarias de integración. Las herramientas de integración solo leen entradas de configuración, cambian las preferencias implementadas, habilitan/deshabilitan o solicitan una recarga.

• Sin suposición de que todos los usuarios de Home Assistant puedan llamar a todos los endpoints. El token de larga duración hereda los permisos y el estado de administrador de su usuario de Home Assistant.

Related MCP server: hass-mcp-server

Arquitectura

flowchart LR
    Client["MCP client"] -->|"Streamable HTTP + MCP bearer token"| HTTP["HTTP transport /mcp"]
    Client -->|"stdio"| Stdio["stdio transport"]
    HTTP --> Policy["MCP tools, schemas, mode, risk and confirmation policy"]
    Stdio --> Policy
    Policy --> REST["Home Assistant REST client"]
    Policy --> WS["Home Assistant WebSocket client"]
    REST --> HA["Home Assistant Core"]
    WS --> HA
    Policy --> TX["Filesystem transaction layer"]
    TX --> Mount["/ha-config allowlisted read-write mount"]
    TX --> Checkpoints[".ha-mcp/backups"]
    TX --> Git["Optional local Git commits"]
    TX -->|"check config, reload, health"| REST
    NoDocker["No Supervisor or Docker socket access"]

El transporte HTTP no tiene estado en la capa de manejadores MCP. El proceso de la aplicación sigue compartiendo su conexión/caché de Home Assistant y serializa las transacciones del sistema de archivos.

Matriz de API de Home Assistant

Revisado el 2026-08-20 contra la documentación actual de Home Assistant y las fuentes dev de home-assistant/core. Un enlace de fuente muestra que un comando interno existe actualmente; no es una garantía de estabilidad.

La API de Home Assistant requiere Authorization: Bearer <HA token>. Consulte la API de autenticación oficial. El endpoint HTTP de MCP tiene un token bearer separado.

Compatibilidad de la API interna

• Los endpoints internos pueden renombrarse, restringirse o tener sus esquemas modificados sin un período de deprecación de API pública. Pruebe contra la versión exacta de Home Assistant antes de habilitar admin en producción.

• Las operaciones de registros, helpers, trazas, salud del sistema, el WebSocket de logbook, metadatos de recorder, entradas de configuración y del editor pueden devolver HA_WS_UNSUPPORTED, HA_INTERNAL_API_UNAVAILABLE, HELPER_STORAGE_API_UNAVAILABLE, errores de permisos o errores de validación de respuesta en versiones incompatibles.

• El núcleo actual de Home Assistant marca muchas mutaciones de registros y lecturas de trazas como exclusivas de administrador. Use un token perteneciente a un administrador cuando esas herramientas sean necesarias; un token de no administrador puede seguir siendo adecuado para un despliegue de solo lectura/control si sus permisos de Home Assistant son suficientes.

• Las mutaciones del editor se limitan a los recursos gestionados por el editor automations.yaml, scripts.yaml y scenes.yaml. Un recurso YAML en ejecución sin un ID de editor utilizable se informa como no editable.

• Los helpers admitidos son input_boolean, input_button, input_text, input_number, input_datetime, input_select, counter, timer y schedule. Sus campos aceptados los determina la versión instalada de Home Assistant.

• Las operaciones de entradas de configuración no inician flujos de configuración, flujos de opciones, reautenticación, reparaciones, OAuth ni entrada de credenciales. Use la interfaz de usuario de Home Assistant para esas operaciones.

• Las vistas previas de dry-run para helpers, registros, áreas, dispositivos, entidades y entradas de configuración no invocan los validadores de mutación de Home Assistant. Su resultado incluye limitaciones que describen ese hecho.

Despliegue en producción

Requisitos previos

• Docker Engine con Compose v2 y BuildKit.

• Una instancia de Home Assistant Core accesible con la API habilitada. El frontend de Home Assistant normalmente la proporciona; las instalaciones solo de API necesitan la integración api.

• Un token de acceso de larga duración de Home Assistant.

• Una ruta del host que contenga la configuración de Home Assistant si se necesitan funciones del sistema de archivos, checkpoint, seguridad de mutación del editor o Git.

• Propiedad y permisos del host que permitan al UID/GID no root configurado leer y escribir en esa ruta.

Los releases de GitHub publican imágenes para múltiples arquitecturas en docker.io/lemanjo/hac-mcp. Use una etiqueta de release exacta en lugar de latest para lograr despliegues reproducibles. Las compilaciones locales siguen siendo compatibles.

Crear un token de Home Assistant

1. Inicie sesión en Home Assistant como el usuario del que debe tomar servicio el sistema.

2. Abra Perfil de usuario y, a continuación, la pestaña Seguridad.

3. En Tokens de acceso de larga duración, seleccione Crear token y asígnele un nombre para este despliegue.

4. Anote el token cuando se muestre; Home Assistant no conserva la cadena del token para mostrarla más adelante.

5. Use una cuenta de administrador solo cuando se requieran herramientas administrativas internas.

Home Assistant documenta la gestión de perfiles aquí y los tokens de larga duración aquí. Los tokens de larga duración son credenciales de alto valor y no deben confirmarse en un repositorio, colocarse en config.example.yaml ni exponerse a un cliente MCP.

Configuración de Compose

cp .env.example .env
cp config.example.yaml config.yaml
install -d -m 700 secrets
openssl rand -hex 32 > secrets/mcp_auth_token
read -rsp "Home Assistant token: " HA_TOKEN
printf '%s' "$HA_TOKEN" > secrets/home_assistant_token
unset HA_TOKEN
chmod 600 secrets/home_assistant_token secrets/mcp_auth_token

Establezca estos valores en .env:

• HOME_ASSISTANT_URL: accesible desde el contenedor. http://host.docker.internal:8123 alcanza un puerto de Home Assistant publicado por el host Linux de Docker porque Compose instala una entrada host-gateway. También funciona una URL de LAN de Home Assistant.

• HA_CONFIG_PATH: directorio de configuración de Home Assistant existente en el host. Se monta en lectura/escritura en /ha-config; Compose se niega a crear una ruta de origen que no existe.

• MCP_SETTINGS_FILE: use ./config.yaml después de hacer cambios específicos del despliegue.

• PUID y PGID:IDs no root con acceso a la HA_CONFIG_PATH.

• MCP_ALLOWED_HOSTS: cada nombre DNS o IP que los clientes pongan en la cabecera de petición Host.

• MCP_BIND_IP: mantenga 127.0.0.1 para un proxy inverso o cliente local; use 0.0.0.0 solo para una exposición intencionada en la LAN.

Valide, compile e inicie:

docker compose config
docker compose build --pull
docker compose up -d
docker compose ps
docker compose logs -f hac-mcp

Para usar un release publicado en lugar de compilar localmente, establezca una etiqueta de imagen exacta y deshabilite las compilaciones:

MCP_IMAGE=docker.io/lemanjo/hac-mcp:0.1.0 docker compose pull hac-mcp
MCP_IMAGE=docker.io/lemanjo/hac-mcp:0.1.0 docker compose up -d --no-build hac-mcp

Endpoints de salud:

curl --fail http://127.0.0.1:3000/livez
curl --fail http://127.0.0.1:3000/readyz

/livez indica que el proceso HTTP está atendiendo peticiones. /readyz realiza una solicitud autenticada a /api/ de Home Assistant y devuelve 503 cuando Home Assistant no está disponible. Ninguno de los dos endpoints requiere el token de portador MCP. La imagen y el healthcheck de Compose usan /livez para que un corte temporal de Home Assistant no provoque un bucle de reinicios.

El sistema de archivos en tiempo de ejecución es de solo lectura, salvo /tmp, los montajes de secretos de Docker y /ha-config. La imagen se ejecuta como un usuario no root y usa tini como PID 1; SIGTERM/SIGINT llegan a Node, que cierra la gestión HTTP y la conexión WebSocket con Home Assistant. Git y los certificados de CA están instalados, pero no hay ninguna herramienta MCP de ejecución de terminal implementada.

Ubicación de en la red

La red Compose suministrada es un bridge aislado con un solo puerto MCP publicado. En ningún caso usa la red del host ni monta un socket de Docker.

Para la conectividad con Home Assistant:

• Home Assistant en el host Docker con un puerto publicado: use http://host.docker.internal:8123.

• Home Assistant en la LAN o en una red macvlan/ipvlan: use su nombre DNS o IP de LAN.

• Home Assistant en otro bridge definido por el usuario: conecte hac-mcp a esa red externa y use el nombre DNS de contenedor de Home Assistant. Reemplace la declaración de red inferior con una red external: true o agregue una segunda red externa al servicio.

Para la conectividad de clientes MCP:

• Mantenga MCP_BIND_IP=127.0.0.1 para clientes del mismo host o un proxy inverso en el mismo host.

• Establezca MCP_BIND_IP=0.0.0.0 para clientes LAN de confianza agregue los IP/nombres DNS de LAN del servidor a MCP_ALLOWED_HOSTS y restrinja el puerto con reglas de firewallets.

• Este servidor no termina TLS. Use un proxy inverso de confianza para el tráfico que cruce una red de no de confianza, conserve la cabecera Authorization y configure los hostnames de origen permitidos si el navegador envía Origin.

Los hosts permitidos y los hostnames de origen mitigan el acceso por DNS rebinding y de origen cruzado; no reemplazan a la autenticación de portador ni a los controles de red. La guía de uso de seguridad de MCP sobre StreamHTTP está en la especificación de transporte.

Unraid

Unraid expone los recursos compartidos de usuario bajo /mnt/user; consulte la documentación oficial de shares. Un esquema típico es /mnt/user/appdata/hac-mcp para los datos del proyecto y los secretos, y el directorio appdata real de Home Assistant para HA_CONFIG_PATH.

1. Coloque el proyecto y los archivos de secretos en una ubicación appdata privada. En la medida de lo posible, mantenga los archivos de secretos con modo 0600 y el directorio con modo 0700.

2. Establezca HA_CONFIG_PATH al directorio en el que exactamente se encuentra el de la config de Home Assistant, por ejemplo /mnt/user/appdata/home-assistant, no monto todo /mnt/user.

3. PUID establezca a 99 y PGID=100 solo si los archivos de Home Assistant tienen el propietario de la cuenta habitual nobody:users de Unraid; de lo contrario, use el propietario no root real. Confirme que esta identidad puede crear /ha-config/.ha-mcp/backups y reemplazar de forma atómica los archivos YAML permitidos.

4. Si tiene instalado el plugin comunitario Docker Compose Manager o una CLI de Compose v2, ejecute la configuración de Compose anterior desde el directorio del proyecto. Los secretos de Compose aparecen como archivos en /run/secrets; Docker documenta ese comportamiento aquí.

5. Sin Compose, construya la imagen home-assistant-admin-mcp:local y cree el contenedor en la interfaz Docker de Unraid usando Vista avanzada. Replique los valores de entorno, puerto y rutas de docker-compose.yml. Vincule los dos archivos de token como solo lectura en /run/secrets/home_assistant_token y /run/secrets/mcp_auth_token; esos bind mounts de la interfaz proporcionan la interfaz de archivos que espera la aplicación, pero no son un objeto de secret de Compose.

6. Use red bridge por defecto. Si Home Assistant usa red del host, apunte HOME_ASSISTANT_URL a la IP-LAN de Unraid y al puerto de Home Assistant, o bien agregue la asignación host.docker.internal:host-gateway. Si Home Assistant tiene una IP-LAN br0 propia, use esa IP. Si ambos contenedores comparten una red Docker personalizada, use el alias de red del contenedor de Home Assistant.

7. Para el acceso MCP desde la LAN, publique el puerto 3000, vincúlelo intencionalmente e incluya la IP o nombre DNS de Unraid en MCP_ALLOWED_HOSTS. Mantenga el token de portador y la restricción del firewall también en una LAN de confianza.

8. No agrega un sistema de ruta de socket de Docker. La administración de contenedores/supervisor no es necesaria ni compatible.

Los ajustes de Mover o de los recursos compartidos de Unraid pueden cambiar dónde se almacena físicamente un archivo en un uso compartido sin cambiar /mnt/user/...; use una única ruta estable de usuario compartido y no mezcle rutas equivalentes de /mnt/user y de /mnt/diskX.

Clientes MCP

Streamable HTTP

Los ejemplos siguientes suponen que el cliente MCP se ejecuta en el mismo host que Docker y que no se han modificado los valores por defecto de Compose. Apunte al cliente hacia:

http://127.0.0.1:3000/mcp

Todas las peticiones a /mcp deben incluir el token MCP separado:

Authorization: Bearer <contents of secrets/mcp_auth_token>

Cargue el token de MCP en el entorno del proceso del cliente sin colocarlo en un archivo de configuración del cliente. Este token autentica únicamente al cliente MCP; nunca use aquí el token de Home Assistant.

export HAC_MCP_TOKEN="$(tr -d '\r\n' < /absolute/path/to/secrets/mcp_auth_token)"

Para un cliente en otro host, cambie 127.0.0.1 direccione el host MCP, y configure MCP_BIND_IP, MCP_ALLOWED_HOSTS, las reglas de firewall y el TLS como se describe en Ubicación de red. Desde otro contenedor, 127.0.0.1 se refiere a ese contenedor cliente; use un alias de comp pora de red de red compartida o una dirección del host en su lugar.

Codex

Agregue esto a ~/.codex/config.toml del usuario o al .codex/config.toml de un proyecto de confianza:

[mcp_servers.home-assistant-admin]
url = "http://127.0.0.1:3000/mcp"
bearer_token_env_var = "HAC_MCP_TOKEN"
enabled = true
default_tools_approval_mode = "writes"
tool_timeout_sec = 150

Reinicie Codex después de configurar HAC_MCP_TOKEN; verifique después la conexión con codex mcp list o con /mcp en la TUI de Codex. El modo de aprobación writes añade una solicitud al cliente para las herramientas no marcadas como solo lectura; el modo del lado del servidor, el riesgo y la política de confirmación se siguen aplicando de forma independiente. Consulte la documentación de Codex MCP.

OpenCode

Incorpore esto en opencode.json del proyecto o en su configuración global de OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "home-assistant-admin": {
      "type": "remote",
      "url": "http://127.0.0.1:3000/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:HAC_MCP_TOKEN}"
      },
      "timeout": 150000
    }
  }
}

Reinicie OpenCode después de configurar HAC_MCP_TOKEN. Ejecute opencode mcp list para comprobar el estado o opencode mcp debug home-assistant-admin para diagnosticar la conexión. En los prompts, mencione el servidor por su nombre cuando sea necesario; por ejemplo, Use home-assistant-admin to list unavailable entities. Consulte la documentación de OpenCode MCP.

Claude Code

Cree o integre este .mcp.json en el proyecto desde el que ejecuta Claude Code:

{
  "mcpServers": {
    "home-assistant-admin": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${HAC_MCP_TOKEN}"
      },
      "timeout": 150000
    }
  }
}

La referencia de variable de entorno es segura para compartir; admítala como token literal en un archivo que se ha confirmado. Tras configurar HAC_MCP_TOKEN, ejecute claude mcp list, abra claude y apruebe el servidor del alcance del proyecto cuando se le pida, y use /mcp para comprobar su estado. Consulte la documentación de MCP de Claude Code.

Verifique y use

Una sonda de inicialización de bajo nivel es útil para diagnosticar fallos de endpoint, proxy y autenticación independientemente de un cliente:

curl --fail-with-body http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer ${HAC_MCP_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-probe","version":"1.0.0"}}}'

Para las operaciones normales use un cliente MCP real; realice correctamente la inicialización, la negociación de la versión del protocolo, las notificaciones y las llamadas a herramientas. El servidor acepta respuestas JSON o SSE en el modo de respuesta auto y usa un controlador HTTP sin estado. Algunos primeros prompts útiles son:

• Use home-assistant-admin to summarize the Home Assistant instance and list unavailable entities. Do not make changes.

• Use home-assistant-admin to diagnose why <entity> is unaffected. Read configuration and recent logs only.

• En control mode: Turn on <explicit entity_id>. Do not target an area or device.

• En admin mode: Dry-run the requested configuration change, show the diff and validation result, and wait for confirmation before applying it.

El cliente no puede elevar el modo configurado del servidor. Inicie en read_only; cambie MCP_MODE en .env y vuelva a crear el servicio de Compose solo después de revisar los permisos y la exposición del despliegue.

stdio

Compile primero con pnpm build y luego configure un cliente MCP local para lanzar el servidor. La autenticación HTTP no se usa en stdio porque el cliente MCP es el propietario del subproceso y la tubería.

{
  "mcpServers": {
    "home-assistant-admin": {
      "command": "node",
      "args": ["/workspaces/hac-mcp/dist/index.js"],
      "env": {
        "MCP_CONFIG_FILE": "/workspaces/hac-mcp/config.example.yaml",
        "MCP_TRANSPORT": "stdio",
        "MCP_MODE": "read_only",
        "HOME_ASSISTANT_URL": "http://homeassistant.local:8123",
        "HOME_ASSISTANT_TOKEN_FILE": "/absolute/private/path/home_assistant_token",
        "HA_CONFIG_PATH": "/absolute/path/to/home-assistant/config"
      }
    }
  }
}

El servidor escribe los registros solo en stderr en modo stdio. El healthcheck de Docker es específico de HTTP, por lo que no use el healthcheck predeterminado de Docker si se ejecuta intencionalmente la imagen como subproceso stdio.

Autenticación y Configuración

Hay dos credenciales independientes:

Para ambos tokens, una variable *_FILE tiene prioridad sobre la variable de entorno directa y se recortan los espacios circundantes:

• HOME_ASSISTANT_TOKEN_FILE sobre HOME_ASSISTANT_TOKEN.

• MCP_AUTH_TOKEN_FILE sobre MCP_AUTH_TOKEN.

MCP_AUTH_TOKEN o su archivo es obligatorio para HTTP y no se requiere para stdio. La comparación de Bearer usa resúmenes SHA-256 y una comparación segura en tiempo. TLS sigue siendo necesario cuando la red no es confiable porque los tokens Bearer son reproducibles.

La configuración se carga desde MCP_CONFIG_FILE; luego los valores de entorno anulan el archivo. Las anulaciones de entorno admitidas son:

Las variables separadas por comas se recortan. Solo las variables de entorno presentes anulan los valores YAML. Los límites, permisos, TTL de caché, política de metadatos de secretos, directorio de backup e identidad de autor de Git provienen de los valores predeterminados de YAML o del archivo de configuración.

Modos, Riesgo y Confirmación

Cada herramienta se registra con un nivel de riesgo y permanece visible para los clientes. La política se aplica de nuevo en la invocación.

call_service tiene una línea base CONTROL, pero eleva argumentos administrativos conocidos antes de la autorización: las acciones de reinicio/detención, backup y purga de registrador se convierten en HIGH_IMPACT; las acciones de recarga, logger y configuración se convierten en CONFIG. El riesgo efectivo se devuelve en cada resultado, y los metadatos MCP personalizados marcan la herramienta como clasificada dinámicamente.

permissions.requireConfirmationFor tiene como valor predeterminado HIGH_IMPACT. Una herramienta que coincida debe recibir confirm: true; de lo contrario, devuelve CONFIRMATION_REQUIRED con metadatos de reintento. Añada CONTROL y/o CONFIG para exigir confirmación de forma más amplia.

La política de dominios sensibles es independiente del modo:

• allow: se aplica la política normal de modo/riesgo.

• confirm: se requiere confirm: true explícito.

• deny: la operación se rechaza incluso en modo admin.

Los valores predeterminados exigen confirmación para lock, alarm_control_panel y siren. Los IDs de entidades de cubierta explícitos que contengan garage o gate también exigen confirmación. La política evalúa cada entidad explícita en un objetivo de múltiples entidades. Los objetivos de área/dispositivo no se pueden expandir de forma segura en el momento de la autorización, por lo que se deniega o se exige confirmación para todo el dominio de servicio cuando esa distinción importa.

Ejecuciones de Prueba

dry_run: true está implementado en herramientas de recurso persistente, helper, registro, área, dispositivo, entidad, entrada de configuración, parche YAML, ciclo de vida administrativo, rollback y llamada de servicio genérica. Las herramientas de control físico de conveniencia no simulan acciones.

• Los parches YAML analizan y validan el YAML resultante y devuelven una diferencia estructurada redactada sin escribir, sin crear checkpoint, sin recargar, sin verificar la configuración completa de Home Assistant ni hacer commit.

• El análisis YAML local rechaza errores de sintaxis, claves de mapeo duplicadas, alias sin resolver y expansión excesiva de alias. Una aplicación no-dry posteriormente ejecuta la verificación completa de configuración de Home Assistant e intenta el rollback ante el rechazo; la validación local no sustituye la validación de dominio de Home Assistant.

• Las ejecuciones de prueba de automatización/script/escena leen el recurso actual del editor, crean un diff JSON e invocan la validación de fragmentos implementada cuando está disponible, pero no escriben ni crean un checkpoint.

• Las ejecuciones de prueba de helper, registro, área, dispositivo, entidad y entrada de configuración leen los datos actuales y construyen una vista previa. No llaman al endpoint interno de mutación ni realizan la validación de mutación del lado del servidor de Home Assistant.

• La ejecución de prueba de recarga de entrada de configuración informa de la recarga propuesta, pero no puede predecir los efectos en tiempo de ejecución.

• Las ejecuciones de prueba de recarga, reinicio, rollback de checkpoint y rollback de Git de servicio validan los identificadores/metadatos actuales disponibles y describen la acción de alto impacto propuesta sin aplicarla.

• call_service genérico admite validación de ejecución de prueba contra la definición de servicio en vivo; el servicio no se llama. Las herramientas de control físico de conveniencia no simulan acciones intencionalmente.

• Una ejecución de prueba exitosa solo demuestra las validaciones descritas en su resultado. No garantiza que el estado, los permisos, las API internas, los archivos o el comportamiento de integración no cambien en el momento de la aplicación.

Seguridad del Sistema de Archivos

El acceso al sistema de archivos se deshabilita como una unidad con HA_FILESYSTEM_ENABLED=false. Cuando está habilitado, las solicitudes se canonicalizan bajo filesystem.root, se verifica cada segmento de ruta y se rechazan los enlaces simbólicos.

Rutas permitidas:

• Cualquier archivo .yaml o .yml directamente bajo la raíz de configuración.

• YAML por debajo de allowedDirectories configurado, con valores predeterminados packages y themes, de forma recursiva hasta la profundidad de escaneo 32.

• .json, .py, .pyi, .yaml y .yml seleccionados bajo custom_components/<integration>/... solo cuando la política de componentes personalizados está habilitada. Las herramientas dedicadas proporcionan lecturas de código fuente limitadas; no se expone ninguna herramienta de escritura de código fuente ni ruta de ejecución/validación de Python.

Siempre protegidas o denegadas:

• .storage, .git, formatos de base de datos de Home Assistant, formatos/nombres de claves privadas y nombres de ruta que coincidan con los patrones implementados de autenticación, credencial, token o clave de backup.

• Rutas fuera de la raíz, segmentos de ruta no válidos, directorios de escritura faltantes, archivos no regulares y todos los enlaces simbólicos.

• Valores de secrets.yaml y secrets.yml de forma predeterminada. Con allowSecretsMetadata: true, las herramientas pueden devolver nombres de claves secretas de nivel superior ordenados, recuento de bytes y marcas de tiempo sin valores.

Con allowSecretValues: false, las claves sensibles en snake_case, camelCase y con guiones como password, clientSecret, token, apiKey, private-key, credential, authorization y cookie se normalizan y redactan de forma recursiva. Los valores !secret/!env_var y las líneas de diferencia coincidentes también se redactan.

Estas comprobaciones se basan en patrones, no en un escáner de contenido, por lo que los nombres de secretos poco comunes pueden no coincidir con todas las protecciones. Mantenga los valores reales en la raíz protegida secrets.yaml, no almacene credenciales en otros YAML permitidos e inspeccione la salida redactada antes de entregarla a un modelo no confiable. Establecer HA_ALLOW_SECRET_VALUES=true permite explícitamente que el YAML con secretos, incluida la raíz secrets.yaml, se lea y se parchee; use esta opción excepcional de recuperación solo con clientes totalmente confiables.

Las escrituras usan archivos temporales, O_NOFOLLOW, fsync, renombrado atómico, modos preservados, comprobaciones de concurrencia optimista SHA-256 y sincronización del directorio padre cuando se admite.

Checkpoints, Transacciones y Rollback

Flujo de trabajo de patch_yaml_file sin ejecución de prueba:

1. Resuelva las rutas permitidas, lea los hashes actuales, aplique las operaciones estructurales YAML y valide la sintaxis.

2. Cree un checkpoint que preserve el modo bajo /ha-config/.ha-mcp/backups de forma predeterminada.

3. Vuelva a verificar los hashes y escriba cada archivo de forma atómica. Solo se ejecuta una transacción de configuración por proceso de servidor.

4. Pida a Home Assistant que verifique su configuración completa.

5. Recargue el dominio de automatización/script/escena afectado, o llame a homeassistant.reload_all para otras rutas o múltiples rutas, a menos que reload: false.

6. Lea la configuración de Home Assistant como comprobación de salud.

7. En un fallo después de que comiencen las escrituras, restaure solo los archivos aplicados si sus hashes aún coinciden con la salida de la transacción, y luego intente la recarga y las comprobaciones de salud.

8. Opcionalmente, haga commit solo de las rutas modificadas en Git. Un fallo de Git se convierte en una advertencia después de un cambio exitoso de Home Assistant; no revierte el cambio.

Las mutaciones de automatización/script/escena gestionadas por el editor crean un checkpoint del sistema de archivos antes de llamar al endpoint interno del editor, requieren el montaje de configuración para cambios sin ejecución de prueba, verifican la configuración del editor y la presencia/ausencia en tiempo de ejecución con reintentos limitados, ejecutan la validación de configuración de Home Assistant e intentan el rollback a nivel de editor si la aplicación o la verificación fallan.

rollback_change primero crea un checkpoint de seguridad de los archivos actuales, restaura el checkpoint seleccionado con comprobaciones de conflicto de hash actual, valida la configuración de Home Assistant y recarga. Si la validación/recarga falla, intenta restaurar el checkpoint de seguridad e informa de cualquier fallo de recuperación. Los checkpoints son instantáneas de archivos locales, no backups de Home Assistant Supervisor, y la limpieza de retención no es automática.

Comportamiento y Límites de Git

Git es opcional y opera solo cuando /ha-config está dentro de un repositorio detectado. La imagen incluye el CLI de Git.

• El estado, el historial y los diffs están restringidos a rutas aceptadas por la política de rutas de configuración.

• Los commits preparan y confirman solo las rutas permitidas seleccionadas. Los hooks están deshabilitados, la firma está deshabilitada y la identidad de autor/committer proviene de la configuración.

• El servidor no inicializa, clona, obtiene, extrae, empuja, fusiona, rebasa, gestiona remotos, credenciales, ramas, etiquetas o submódulos.

• Las rutas de destino se verifican antes de la mutación. Si un archivo afectado ya tiene cambios preparados o en el árbol de trabajo, la operación de Home Assistant puede continuar con su punto de control, pero el commit automático de Git se omite para que las ediciones humanas preexistentes no se incluyan en un commit de MCP. Las rutas no relacionadas permanecen intactas.

• rollback_to_commit acepta solo el HEAD actual, solo un commit cuyo correo electrónico del autor coincida con el correo electrónico de servicio configurado, no un commit inicial, y solo cuando las rutas afectadas no tienen cambios sin confirmar.

• El rollback de Git escribe un nuevo commit compensatorio en lugar de restablecer el historial. Si la validación de Home Assistant falla, se intenta otro rollback propiedad del servicio para restaurar el estado anterior.

• Los comandos de Git agotan el tiempo de espera después de 30 segundos. La salida normal está limitada a 4 MiB; los diffs están limitados a cuatro veces maxReadBytes, con un máximo de 16 MiB.

Herramientas

Los nombres a continuación se derivan de src/mcp/tools. Los esquemas visibles para el cliente, descripciones, anotaciones, riesgo, fuente y metadatos de estabilidad son devueltos por el descubrimiento de MCP.

Descubrimiento

• Instancia: get_home_assistant_info, get_system_health, get_config.

• Integraciones: list_integrations, get_integration.

• Áreas: list_areas, get_area.

• Dispositivos: list_devices, get_device, search_devices.

• Entidades: list_entities, get_entity, search_entities.

• Búsqueda entre registros: search_home_assistant_registry.

Tiempo de ejecución e historial

• Servicios/eventos: list_services, list_event_types, get_events, subscribe_events.

• Estados: get_state, get_states, get_states_by_area, get_states_by_device.

• Datos del grabador: get_history, get_logbook, get_statistics, get_recorder_statistics.

Control

• Control genérico/estándar: call_service, turn_on, turn_off, toggle, set_value, set_temperature.

• Ejecución: activate_scene, run_script.

Automatizaciones, scripts, escenas y trazas

• Automatizaciones: list_automations, get_automation, create_automation, update_automation, delete_automation, enable_automation, disable_automation, trigger_automation, reload_automations, validate_automation.

• Scripts: list_scripts, get_script, create_script, update_script, delete_script, run_script_by_id, reload_scripts, validate_script.

• Escenas: list_scenes, get_scene, create_scene, update_scene, delete_scene, activate_scene_resource, reload_scenes.

• Trazas de automatización: get_automation_traces, get_automation_trace, explain_automation_failure, get_last_automation_run.

• Trazas genéricas: get_trace, list_traces, explain_trace, get_last_trace.

Ayudantes y registros

• Ayudantes: list_helpers, get_helper, create_helper, update_helper, delete_helper.

• Registro de entidades: update_entity_registry, disable_entity, enable_entity, rename_entity, move_entity_to_area.

• Registro de dispositivos: update_device, rename_device, move_device_to_area, disable_device, enable_device.

• Registro de áreas: create_area, update_area, delete_area, assign_device_to_area, assign_entity_to_area.

• Entradas de configuración: get_config_entries, get_config_entry, reload_config_entry, update_integration, enable_integration, disable_integration.

Configuración y recuperación

• Leer/listar: read_configuration, list_configuration_files, read_yaml_file, list_custom_component_files, read_custom_component_source.

• Parchear/validar: patch_yaml_file, validate_configuration, validate_home_assistant_configuration.

• Recargar/reiniciar: reload_configuration, reload_yaml_configuration, restart_home_assistant.

• Historial/diff: get_config_history, get_config_diff, get_recent_changes.

• Rollback: rollback_change, rollback_to_commit.

Registros, diagnósticos, dependencias y búsqueda

• Registros: get_home_assistant_logs, search_logs, get_errors, get_warnings, get_recent_errors, get_integration_errors.

• Hallazgos de entidades/dispositivos: find_unavailable_entities, find_disabled_entities, find_orphaned_entities, find_orphaned_devices, find_duplicate_entities, find_entities_without_area, find_devices_without_area, find_stale_sensors.

• Hallazgos de automatizaciones/ayudantes: find_unused_helpers, find_broken_automations, find_automation_errors, find_automations_referencing_missing_entities.

• Dependencias/búsqueda: get_entity_dependencies, get_automation_dependencies, search_home_assistant.

Ejemplos de solicitudes de usuario

• "Lista las entidades no disponibles en la cocina e incluye sus relaciones de dispositivo e integración."

• "Muestra las entradas de registro ERROR y CRITICAL para la integración zha de la última hora."

• "Explica la ejecución fallida más reciente del ID de automatización garage_arrival."

• "Encuentra automatizaciones que referencian entidades faltantes y luego muestra las dependencias de cada automatización."

• "Haz una prueba en seco de un parche YAML estructural que cambie packages/lighting.yaml; muestra solo el diff redactado."

• "Apaga light.office, pero no apuntes a ninguna otra entidad."

• "Crea un ayudante input_boolean para el modo invitado como prueba en seco e informa las limitaciones de validación."

• "Elimina el ID de escena old_evening con confirmación explícita y luego informa el punto de control, la validación de configuración, la verificación, el rollback y los resultados de Git."

El modelo/cliente debe traducir una solicitud al esquema exacto de la herramienta. Una solicitud en lenguaje natural no elude los controles de modo, riesgo, confirmación, ruta o autorización de Home Assistant.

Rendimiento y límites

Los valores predeterminados y los límites estrictos están diseñados para evitar que una llamada de MCP se convierta en una consulta ilimitada de Home Assistant o del sistema de archivos.

Las ventanas largas de historial/libro de registro y los diagnósticos completos aún pueden ser costosos dentro del grabador de Home Assistant. Filtra por entidad, dispositivo, integración, rango de tiempo y página siempre que sea posible.

Desarrollo

Se requieren Node.js 22.23.1 y pnpm 11.21.0.

corepack enable
pnpm --version
pnpm install --frozen-lockfile
pnpm build

Cadena de suministro de dependencias

• Las dependencias directas usan versiones exactas; el archivo de bloqueo fija el gráfico completo con hashes de integridad del registro.

• pnpm rechaza versiones publicadas hace menos de 10,080 minutos (siete días), paquetes sin tiempos de publicación, degradaciones de confianza del editor, fuentes transitivas exóticas y scripts de compilación de dependencias no aprobados. También revalida los datos de resolución del archivo de bloqueo contra el registro npm fijado en cada instalación.

• Las instalaciones usan un archivo de bloqueo congelado por defecto. Los cambios de dependencias requieren un pnpm install --no-frozen-lockfile explícito y revisado, seguido de pnpm supply-chain:check, el conjunto de validación normal y un diff del archivo de bloqueo confirmado.

• Los overrides transitivos fijan versiones elegibles de content-type y hono mientras las versiones más nuevas permanecen dentro de la ventana de cuarentena, y fijan undici-types a una versión atestiguada que no degrada la confianza del editor. Reevalúa, pero no elimines automáticamente, estos overrides durante una actualización de dependencias revisada.

• Las acciones de CI y las imágenes base de contenedores usan digests de contenido o commit inmutables. Los paquetes Debian en tiempo de ejecución provienen de una instantánea fechada, por lo que reconstruir no los actualiza silenciosamente.

• No agregues una excepción minimumReleaseAgeExclude. Para una versión de seguridad urgente, espera hasta que haya envejecido siete días u obtén aprobación explícita para cambiar esta política en un cambio revisado.

Publicación de versiones

Publicar una versión de GitHub con una etiqueta SemVer como v0.1.0 ejecuta .github/workflows/release-docker.yml. Compila imágenes linux/amd64 y linux/arm64, empuja la etiqueta de versión a docker.io/lemanjo/hac-mcp y adjunta atestaciones de SBOM y procedencia. Las versiones estables también actualizan latest; las versiones preliminares no.

El repositorio necesita estos secretos de GitHub Actions:

• DOCKERHUB_USERNAME: nombre de cuenta de Docker Hub, actualmente lemanjo.

• DOCKERHUB_TOKEN: un token de acceso personal de Docker Hub con permiso de lectura/escritura para lemanjo/hac-mcp. No uses la contraseña de la cuenta.

Agrégalos en GitHub repository > Settings > Secrets and variables > Actions > New repository secret, o con GitHub CLI:

gh secret set DOCKERHUB_USERNAME --repo lemanjo/hac-mcp --body lemanjo
gh secret set DOCKERHUB_TOKEN --repo lemanjo/hac-mcp

El segundo comando solicita el valor del token de forma segura. No almacenes el token en .env, YAML de flujo de trabajo, historial de shell o el repositorio.

Cada push a main, incluida una solicitud de extracción fusionada, ejecuta .github/workflows/nightly-docker.yml. Utiliza el secreto separado DOCKERHUB_NIGHTLY_TOKEN y publica nightly además de una etiqueta inmutable nightly-<full-commit-sha>. El flujo de trabajo también puede iniciarse manualmente desde GitHub Actions. Usa la etiqueta de SHA completo cuando la reproducibilidad sea importante.

gh secret set DOCKERHUB_NIGHTLY_TOKEN --repo lemanjo/hac-mcp

Desarrollo HTTP:

HOME_ASSISTANT_URL=http://homeassistant.local:8123 \
HOME_ASSISTANT_TOKEN_FILE=/absolute/private/path/home_assistant_token \
MCP_AUTH_TOKEN_FILE=/absolute/private/path/mcp_auth_token \
MCP_CONFIG_FILE=./config.example.yaml \
MCP_TRANSPORT=http \
MCP_HOST=127.0.0.1 \
MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
HA_CONFIG_PATH=/absolute/path/to/home-assistant/config \
pnpm dev

Para desarrollo solo de API, establece HA_FILESYSTEM_ENABLED=false y HA_GIT_ENABLED=false; las mutaciones de recursos del editor que requieren puntos de control no estarán disponibles por diseño.

Pruebas y Validación

Ejecuta las comprobaciones del repositorio:

pnpm supply-chain:check
pnpm audit --prod --audit-level high
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm build

Valida los archivos de despliegue donde Docker esté disponible:

docker compose config
docker build --check -t home-assistant-admin-mcp:check .
docker build -t home-assistant-admin-mcp:local .

Luego prueba /livez, /readyz, una solicitud de inicialización MCP y herramientas de solo lectura representativas contra una instancia de Home Assistant que no sea de producción. Antes de habilitar admin, prueba lecturas de API internas, ejecuciones en seco, una mutación desechable, la reversión de puntos de control y el comportamiento de Git contra la versión exacta de Home Assistant y el sistema de archivos utilizados en producción.

Solución de Problemas

El Servidor No Se Inicia

• INVALID_CONFIGURATION: analiza config.yaml, verifica las claves exactas en camelCase, los rangos numéricos, las URL, el formato de correo electrónico y los detalles de validación aplanados en stderr.

• MCP_AUTH_REQUIRED: HTTP requiere MCP_AUTH_TOKEN o MCP_AUTH_TOKEN_FILE, con al menos 16 caracteres después de recortar.

• ENOENT para un secreto: las rutas de origen de los secretos de Compose son rutas de host relativas al proyecto de Compose. Confirma .env y los permisos de archivo.

• La comprobación de salud de Docker falla en modo stdio: /livez solo existe en modo HTTP; elimina o anula la comprobación de salud para contenedores stdio intencionales.

MCP HTTP 401, 403 O 413

• 401: el token portador MCP está ausente, malformado o es incorrecto. El esquema de autenticación no distingue entre mayúsculas y minúsculas y debe ser Bearer.

• 403 antes de una llamada a herramienta: añade el nombre de host real de la solicitud a MCP_ALLOWED_HOSTS y, para clientes de navegador, su nombre de host de origen sin esquema ni puerto a MCP_ALLOWED_ORIGINS. No añadas comodines arbitrarios.

• 413 o rechazo de análisis JSON: reduce la solicitud o aumenta mcp.maxRequestBytes dentro del límite de 10 MiB.

• Fallos de proxy inverso: conserva Authorization, Host, Origin, Accept, Content-Type, MCP-Protocol-Version, el streaming HTTP y el comportamiento de SSE.

/readyz Devuelve 503 O Las Llamadas A Home Assistant Fallan

• Desde dentro de un contenedor puente, localhost es el contenedor MCP, no Home Assistant. Usa host.docker.internal, una dirección LAN o un alias de red compartida.

• HA_AUTH_FAILED/HA_WS_AUTH_FAILED: reemplaza o recrea el token de larga duración de Home Assistant.

• HA_PERMISSION_DENIED: el usuario del token carece de permiso o estado de administrador para el comando interno solicitado.

• HA_TLS_ERROR/HA_WS_TLS_ERROR: instala una cadena de certificados de confianza o, solo en una red privada controlada, establece HA_VERIFY_TLS=false con plena conciencia de que la identidad del servidor ya no se verifica.

• Errores de historial, libro de registro o estadísticas: verifica que la integración del recorder/logbook esté cargada y que los ID y rangos de tiempo solicitados existan.

El Sistema De Archivos O Git Fallan

• CONFIG_ROOT_UNAVAILABLE/permiso denegado: haz que HA_CONFIG_PATH sea correcto y escribible por PUID:PGID; el contenedor intencionalmente no se ejecuta como root.

• CONFIG_PATH_NOT_ALLOWED: usa YAML raíz o un directorio permitido; las rutas protegidas, los enlaces simbólicos, las extensiones arbitrarias y los directorios principales faltantes se rechazan.

• CONFIG_CONCURRENT_MODIFICATION/ROLLBACK_CONFLICT: otro proceso cambió el archivo. Vuelve a leer, revisa y reintenta en lugar de forzar una sobrescritura.

• Git is enabled but no repository was detected: inicializa/gestiona el repositorio fuera de MCP o establece HA_GIT_ENABLED=false.

• Git informa propiedad dudosa: alinea el UID/GID del contenedor con la propiedad del repositorio. No lo resuelvas ejecutando el contenedor como root.

• Los puntos de control consumen espacio: inspecciona y aplica una política de retención definida por el operador en .ha-mcp/backups; no existe una herramienta de eliminación automática.

Las Herramientas Internas Fallan Después De Una Actualización De Home Assistant

• Confirma que el comando aún existe en el código fuente principal actual vinculado y compara los campos de solicitud/respuesta.

• Reintenta primero una operación de solo lectura. No reintentes repetidamente una mutación cuando el estado de verificación o reversión sea incierto.

• Usa la interfaz de usuario de Home Assistant para asistentes, integraciones o recursos cuyo endpoint interno haya cambiado.

• Mantén MCP_MODE=read_only hasta que la compatibilidad se pruebe y revise.

Licencia

MIT