ha-mcp Home Assistant: proteger un agente de IA en casa

ha-mcp Home Assistant: servidor MCP no oficial (MIT) para controlar tu casa con un agente de IA. Token, solo lectura, aprobación y registros que leer.
ha-mcp Home Assistant : sécuriser un agent IA à la maison

ha-mcp Home Assistant: es un servidor MCP no oficial, publicado en GitHub en el repositorio homeassistant-ai/ha-mcp, que permite a un asistente de IA (Claude, ChatGPT, Gemini CLI y otros) leer y controlar una instalación de Home Assistant en lenguaje natural. Según su página de GitHub el 27 de octubre de 2026, el repositorio tiene unas 5300 estrellas (GitHub muestra «5.3k», un valor redondeado) y 255 forks, con licencia MIT.

Para un equipo SRE, el interés va más allá de la domótica. Este repositorio es un caso de manual: un agente recibe las llaves de un pequeño sistema de producción hecho de luces, cerraduras, automatizaciones y copias de seguridad. Las preguntas útiles son quién puede llamar al servidor, con qué permisos y qué pasa si una acción no se puede deshacer. Este artículo sigue el README, SECURITY.md, las preguntas frecuentes y el archivo LICENSE del repositorio, leídos hoy.

Una precisión de honestidad: span.observer es un blog independiente, sin relación con Home Assistant ni con los autores del proyecto, y no ha instalado ni ejecutado ha-mcp. El proyecto se describe como «The Unofficial and Awesome Home Assistant MCP Server». Las capturas de abajo son extractos generados a partir de los archivos del repositorio.

ha-mcp Home Assistant: lo que dice el repositorio

  • Licencia: el archivo LICENSE es una licencia MIT.
  • Lenguaje y framework: Python 3.13 o superior (requires-python = ">=3.13,<3.15" en pyproject.toml), construido con FastMCP, según el README.
  • Versión: pyproject.toml y el CHANGELOG indican la versión 8.7.0 del 14 de octubre de 2026. No pude leer un número de release en la página de GitHub; el último commit que leí es del 26 de octubre de 2026.
  • Alcance: el README anuncia 87 herramientas: búsqueda de entidades, llamadas a servicios, automatizaciones, scripts, paneles, historial, registros, copias de seguridad, registro de dispositivos y reinicio de Home Assistant.
  • Diferencia con el servidor MCP integrado: según el README, el de Home Assistant se apoya en Assist y solo ve las entidades expuestas a Assist; ha-mcp cubre «todo lo que hay en Home Assistant», incluida la creación y edición de configuración.

Esa diferencia es el centro del asunto: cuanto más puede configurar el agente, mayor es la superficie de riesgo.

Servidor MCP de Home Assistant: la superficie de riesgo

Tres puntos de SECURITY.md merecen una lectura antes de instalar nada.

  • Un cliente autenticado es un «principal de confianza». El archivo dice que ha-mcp no intenta defenderse de un cliente MCP malicioso o comprometido, y que la inyección de prompts es responsabilidad del cliente.
  • Los permisos vienen del token. ha-mcp usa el token de acceso de larga duración que se le entrega; con un token de administrador puede hacer operaciones de administrador. El proyecto espera un token de administrador y, para limitar al agente, recomienda sus políticas de seguridad por herramienta o desactivar herramientas en lugar de usar un token sin privilegios.
  • La red local es la zona de confianza. En modo estándar, la autenticación se basa en un secreto en la ruta de la URL; cualquier equipo que llegue a esa ruta se trata como de confianza. Por defecto, los puntos de entrada HTTP escuchan en 0.0.0.0; MCP_HOST=127.0.0.1 lo limita a la máquina local.
Extractos de SECURITY.md del repositorio homeassistant-ai/ha-mcp: un cliente MCP autenticado es un principal de confianza, los permisos dependen del token entregado y MCP_HOST=127.0.0.1 limita la escucha a la máquina local
Source : github.com

El mismo archivo añade que en modo estándar todos los clientes que comparten el mismo secreto tienen un acceso idéntico, sin aislamiento entre clientes. Para el acceso desde Internet, SECURITY.md remite al modo OAuth (descrito como beta) o a OIDC detrás de un proxy inverso TLS. Para los principios generales, consulta cómo proteger un servidor MCP y las lecciones SRE del MCP para el gran público.

Limitar al agente: solo lectura, políticas, aprobación

En la categoría «Safety», el README enumera un modo de solo lectura, la activación o desactivación por herramienta, políticas de seguridad de herramientas (aprobación del usuario) y copias de seguridad automáticas de las ediciones.

Solo lectura por conexión

Según el README, añadir /readonly a la URL del servidor HTTP restringe esa conexión al modo de solo lectura mientras otros clientes conservan el acceso normal. Las herramientas de escritura se ocultan y sus llamadas se bloquean, incluidas las hechas mediante herramientas en caché.

Extracto del README de ha-mcp: dos direcciones de ejemplo, una normal y otra que termina en /readonly, y la regla que oculta las herramientas de escritura en la conexión de solo lectura
Source : github.com

Ojo: el README precisa que es un modo de conexión y no un permiso sobre la credencial: las mismas credenciales siguen funcionando en la dirección normal. Un secreto filtrado sigue dando acceso completo.

Modo de solo lectura global

La documentación de la aplicación (add-on) describe la opción read_only_mode, desactivada por defecto: retira las herramientas de escritura de la lista y bloquea toda escritura con un error READ_ONLY_MODE. Los usos citados son análisis, auditoría y demostraciones. Hace falta reiniciar la aplicación.

Aprobación humana de las acciones sensibles

Las preguntas frecuentes describen reglas «Tool Security Policies» que retienen una llamada hasta que se aprueba en la interfaz de ajustes. Cada solicitud se anuncia también en el bus de eventos de Home Assistant como ha_mcp_approval_requested, con los campos token, tool_name, args, created_at y expires_at.

Extracto de docs/FAQ.md de ha-mcp: una automatización de Home Assistant activada por el evento ha_mcp_approval_requested que envía una notificación con el nombre de la herramienta y sus argumentos
Source : github.com

Las preguntas frecuentes advierten de que los argumentos largos se recortan pero no se ocultan: un argumento corto se difunde tal cual en el bus. Aprobar desde una notificación está desactivado por defecto y exige un PIN.

Instalación paso a paso

El README recomienda el «HA-MCP Custom Component», instalado con HACS, que ejecuta el servidor dentro de Home Assistant. Su inicio rápido menciona la versión 9.0.0 (28 de octubre de 2026) y posteriores: esa fecha es posterior al día en que lo leí, así que comprueba las pantallas con tu versión.

  1. Instala el componente desde HACS (repositorio personalizado https://github.com/homeassistant-ai/ha-mcp, categoría Integration) y reinicia Home Assistant.
  2. Decide con qué cuenta de administrador actúa el servidor. El README considera más seguro crear una cuenta dedicada (Ajustes, Personas) con «Allow login», «Local access only» y «Administrator». Un token de tu propia cuenta «funciona desde cualquier sitio si se filtra».
  3. Añade la integración (Ajustes, Dispositivos y servicios) y elige cómo se conectan los clientes: acceso remoto por webhook (empieza con «Secret URL») y/o acceso a la red local. Ambos empiezan desactivados.
  4. Copia la URL de conexión desde la pantalla Configure y pégala en tu cliente de IA.

Otros métodos según el README: la aplicación de Home Assistant (HAOS y Supervised), Docker, PyPI con uvx o stdio local (no recomendado, se señalan problemas de transporte). Configura un solo método por cliente. Para probarlo sin tocar tu casa, el README ofrece scripts de instalación que apuntan a un servidor de demostración; lee un script antes de ejecutarlo.

Límites y puntos abiertos

  • Anclaje que matizar: proyecto activo (muchos colaboradores listados, CHANGELOG detallado) pero muy cambiante, con varios modos de instalación y autenticación. El README anuncia un cambio incompatible en la v7.3.0 y deja funciones en beta (archivos, YAML, herramientas personalizadas). GitHub redondea el número de estrellas.
  • Fechas por comprobar: el README menciona una versión 9.0.0 fechada el 28 de octubre de 2026, mientras que la versión leída en el código es la 8.7.0.
  • Herramientas de escritura sensibles: entre las 87 herramientas hay reinicio, borrado de dispositivos y entidades, restauración de copias y, en beta, escritura de archivos. Algunas acciones no se deshacen con un simple retroceso.
  • Secreto en la URL: las preguntas frecuentes desaconsejan pegarlo en capturas, registros públicos o conversaciones.
  • Datos: PRIVACY.md dice que ha-mcp no recoge telemetría en junio de 2026 (una recogida anónima está «prevista»), pero lo que lee el agente pasa por tu cliente de IA y su proveedor.
  • Proyecto no oficial: no lo desarrolla ni lo garantiza Home Assistant.

Observar el servidor MCP

La documentación que leí no describe ninguna exportación de trazas ni métricas de OpenTelemetry. pyproject.toml sí lista la biblioteca opentelemetry-api entre sus dependencias, pero nada indica que exporte trazas: no montes una supervisión sobre ella sin comprobarlo. Lo que sí describe la documentación:

  • Registros del servidor: la pestaña Logs de la aplicación, o docker logs ha-mcp con Docker. Las preguntas frecuentes citan dos líneas normales: «Terminating session: None» (modo HTTP sin estado) y un 405 en un GET.
  • Diagnóstico del transporte HTTP: la opción HAMCP_HTTP_TRANSPORT_DIAGNOSTICS=true (desactivada por defecto, requiere reinicio) registra en nivel INFO los bytes, la duración, las desconexiones y el tipo de excepción, con un identificador de traza generado por el servidor. Sin cuerpos, credenciales ni rutas secretas.
  • Eventos de aprobación: ha_mcp_approval_requested en el bus de Home Assistant permite contar y alertar sobre las acciones retenidas.
  • Del lado de Home Assistant: las herramientas ha_get_logs y ha_get_automation_traces leen registros y trazas de automatizaciones.

Para trazar las llamadas a herramientas de extremo a extremo, el cliente o el agente debe emitir los spans: consulta observar agentes MCP con OpenTelemetry. Un proyecto vecino del mismo tipo: Agent Reach.

Buenas prácticas

  • Empieza en solo lectura (/readonly o read_only_mode) y abre la escritura solo si hace falta.
  • Crea una cuenta de administrador dedicada en lugar de usar tu token personal.
  • Mantén el acceso local; si necesitas acceso remoto, prefiere el inicio de sesión de Home Assistant u OIDC antes que un secreto solo.
  • Exige aprobación humana para las herramientas destructivas (borrado, restauración, reinicio).
  • Rota un secreto expuesto y vigila los registros; consulta las barreras de seguridad de los agentes de IA.

Preguntas frecuentes

¿Es ha-mcp un proyecto oficial de Home Assistant?

No. El repositorio se presenta como «Unofficial». Home Assistant tiene su propio servidor MCP integrado, que el README compara con ha-mcp.

¿Puede un agente modificarlo todo?

Puede hacer lo que permita el token entregado, según SECURITY.md. Con un administrador, eso incluye operaciones de administración; el modo de solo lectura, la desactivación de herramientas y las políticas de aprobación acotan ese alcance.

¿Envía el proyecto datos a su autor?

Según PRIVACY.md (junio de 2026), no se recoge telemetría; los informes de errores solo se envían con tu acuerdo. Tus datos sí los procesa el cliente de IA que conectes.

Conclusión

ha-mcp muestra lo que ocurre cuando se confía un sistema real a un agente: casi toda la seguridad depende de los permisos del token, del secreto de la URL y de las barreras de aprobación. Trátalo como un componente que hay que restringir desde el primer día. Fuentes: repositorio homeassistant-ai/ha-mcp (README, SECURITY.md, docs/FAQ.md, LICENSE), leídas el 27 de octubre de 2026.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC, ni a Home Assistant, ni a los autores de ha-mcp ni a los proyectos citados. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba siempre los comandos y opciones en su documentación oficial.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
CLAUDE.md Karpathy : mesurer l'effet sur un agent de code

CLAUDE.md Karpathy: cómo medir su efecto en un agente de código

Next Post
Dynatrace Assist agentique : ce qu'il fait, ce qu'il ne fait pas

Dynatrace Assist agéntico: qué hace, qué no hace y sus barreras

Related Posts