Home Assistant MCP

Un servidor Model Context Protocol (MCP) protegido con OAuth para conectar de forma segura ChatGPT, Codex y otros clientes MCP a Home Assistant.

El proyecto expone 99 herramientas tipadas para descubrimiento, paneles de control, horarios, clima, energía, medios, limpieza, riego, automatizaciones, diagnósticos y control de dispositivos cuidadosamente acotado. Mantiene la API de Home Assistant privada y evita deliberadamente convertirse en un shell genérico, lector de registros, escáner de red o proxy de servicios sin restricciones.

[!IMPORTANT] Esta es una implementación de referencia sensible a la seguridad para una instalación de Home Assistant autoalojada. Lea el modelo de seguridad, reemplace cada valor de ejemplo y revise las listas de permitidos antes de conectarlo a un hogar real.

Aspectos destacados

• Acceso tipado a Home Assistant: entidades, dispositivos, áreas, historial, clima, calendarios, horarios, estadísticas, integraciones, paneles de control, listas de tareas, automatizaciones, copias de seguridad y salud del sistema.

• Escrituras acotadas: clima, luces, escenas, reproductores multimedia, aspiradoras, cubiertas, cerraduras, sirenas, notificaciones, paneles de control, horarios, calendarios, elementos de tareas y automatizaciones utilizan entradas validadas y listas de servicios restringidas.

• Soporte para aspersores: estado del controlador en vivo, metadatos de zonas, configuración, historial de riego, actualización de telemetría, inicio de zonas o secuencias y operaciones de parada idempotentes.

• Energía y SolarEdge: producción, comparación de módulos, flujo de energía, desgloses de energía, resúmenes de almacenamiento, telemetría, alertas y una integración de puente opcional para Home Assistant.

• Sincronización de capacidades persistente: compara el registro de servicios actual de Home Assistant con la línea base de la versión revisada cada cinco minutos e informa desviaciones sin exponer dinámicamente nuevas escrituras.

• Diagnósticos saneados: evidencia de LAN opcional de ruta fija, host/tiempo de ejecución, interrupciones y subred fija con límites estrictos y sin direcciones sin procesar, objetivos arbitrarios, comandos o control de dispositivos.

• Acceso remoto nativo OAuth: flujo de código de autorización con S256 PKCE, registro dinámico de clientes, tokens de acceso con alcances y metadatos de recursos MCP.

La versión 2.6.1 anuncia actualmente 99 herramientas. Consulte CHANGELOG.md para el historial de versiones.

Arquitectura

flowchart LR
    Client[ChatGPT, Codex, or MCP client]
    Edge[HTTPS edge<br/>Cloudflare Worker, tunnel, or reverse proxy]
    MCP[Home Assistant MCP<br/>OAuth + typed tools]
    HA[Private Home Assistant API]
    Data[(OAuth, audit, and<br/>capability-sync state)]
    Collector[Optional root-owned<br/>diagnostics collector]
    Export[Sanitized read-only export]

    Client -->|HTTPS + OAuth/PKCE| Edge
    Edge -->|loopback or shared-secret origin| MCP
    MCP -->|long-lived service token| HA
    MCP --> Data
    Collector --> Export --> MCP

La implementación de referencia vincula el servicio MCP a 127.0.0.1:8000. Solo el borde HTTPS es público. Home Assistant puede permanecer local al host o ser accesible a través de una red privada.

Superficie de herramientas

Las acciones de mayor riesgo se anotan como destructivas y requieren un argumento de confirmación explícito. El registro exacto es autoritativo; inspecciónelo desde un cliente MCP autenticado después de la implementación.

Requisitos

• Home Assistant accesible desde el host MCP.

• Un token de acceso de larga duración dedicado de Home Assistant. Use una identidad de servicio separada cuando sea posible.

• Python 3.12 o superior y uv para desarrollo y pruebas.

• Docker con Compose para la implementación de contenedor de referencia.

• Una URL HTTPS pública para clientes MCP remotos.

• Un borde HTTPS que llegue al MCP a través de loopback o inyecte el secreto compartido de origen configurado. Los ejemplos incluidos de Caddy y Cloudflare demuestran esos dos patrones.

• Linux y systemd solo si se usa el recolector de diagnósticos de host opcional.

El archivo Compose incluido es una referencia de producción, no un instalador universal de un solo comando. Asume red de host, una configuración existente de Home Assistant en /opt/homeassistant/config y una exportación de diagnósticos instalada en /var/lib/ha-host-diagnostics/export. Adapte esos montajes a su instalación sin exponer la API de Home Assistant ni el socket de Docker.

Inicio rápido para desarrollo

Clone el repositorio e instale las dependencias bloqueadas:

git clone https://github.com/shogun301/ha-chatgpt-mcp.git
cd ha-chatgpt-mcp
uv sync --frozen

La suite de pruebas y la auditoría de código fuente público no necesitan credenciales de producción:

uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

Para ejecutar el servicio, copie .env.example a un .env ignorado, reemplace cada dominio e ID de entidad de ejemplo y proporcione las rutas de tiempo de ejecución y los archivos de secretos requeridos que se describen a continuación. La aplicación no carga .env automáticamente; exporte las variables en su administrador de procesos, use uvicorn --env-file .env o deje que Docker Compose lo cargue.

Para un proceso local después de configurar el entorno:

uv run uvicorn app.server:app --host 127.0.0.1 --port 8000 --no-proxy-headers

Para la implementación de contenedor de referencia después de adaptar sus montajes e integraciones opcionales:

docker compose build --pull
docker compose up -d
curl --fail http://127.0.0.1:8000/healthz

No vincule Uvicorn directamente a una interfaz pública.

Configuración

Configuración principal

Las variables específicas de entidad en .env.example mapean la superficie de herramientas genérica a las entidades de presencia, notificación, aspiradora, aspersor, termostato y horario de una implementación. Mantenga los ID de entidad reales en la configuración local, no en Git.

Archivos de secretos requeridos

El servidor lee los secretos de archivos en lugar de valores de entorno:

Genere valores aleatorios con un generador criptográficamente seguro. Se puede producir un hash de contraseña Argon2 sin colocar la contraseña en el historial del shell:

uv run python -c "from argon2 import PasswordHasher; from getpass import getpass; print(PasswordHasher().hash(getpass('OAuth password: ')))"
uv run python -c "import secrets; print(secrets.token_urlsafe(48))"

Almacene las salidas en archivos separados con permisos de solo propietario. Nunca confirme secrets/, .env, tokens, contraseñas, hashes, dominios privados, inventarios de entidades, horarios o topología de red.

Configuración opcional de SolarEdge

El soporte de SolarEdge utiliza credenciales de cliente opcionales, un almacén de tokens cifrado, secreto de puente, URI de redirección y credenciales de respaldo de portal protegidas. Si no usa SolarEdge, omita las variables SOLAREDGE_*_FILE correspondientes. El archivo Compose de referencia establece esas rutas, así que proporcione los archivos o elimine esas entradas en su anulación local.

Alcances de OAuth

• mcp:read permite herramientas de lectura.

• mcp:write permite la superficie de escritura revisada y también satisface la concesión de compatibilidad más fuerte actual.

• mcp:diagnostics, junto con mcp:read, permite diagnósticos privilegiados de solo lectura de host y LAN sin otorgar escrituras de dispositivos.

Conecte los clientes a https://your-mcp-host.example/mcp. El servidor publica metadatos de servidor de autorización OAuth, recurso protegido, configuración OpenID y registro dinámico de clientes bajo el mismo origen.

Opciones de borde

La aplicación requiere que las solicitudes que no sean de loopback lleven el secreto compartido de origen configurado. Se incluyen dos ejemplos:

• cloudflare/ contiene un proxy Worker de Cloudflare estrecho. Reenvía solo las rutas MCP, OAuth, salud y callback de SolarEdge, aplica un límite de solicitud de 1 MiB, agrega el secreto de origen y elimina encabezados innecesarios.

• Caddyfile proporciona un proxy inverso HTTPS en el mismo host al listener MCP de loopback.

El servicio cloudflared incluido usa un archivo de token y publica métricas solo en loopback. Reemplace todas las rutas de ejemplo y mantenga el origen MCP, la API de Home Assistant y el listener de métricas fuera de la red pública.

Sincronización de capacidades

Las integraciones de Home Assistant pueden agregar o eliminar servicios independientemente de este proyecto. Por lo tanto, el servidor consulta el registro de servicios de Home Assistant cada cinco minutos y persiste una línea base vinculada a la versión en /data/ha-capability-sync.json.

get_capability_sync_status informa servicios agregados o eliminados y cambios en el esquema de campos entre reinicios. El monitor es deliberadamente observacional: nunca llama a un servicio y nunca convierte un servicio de Home Assistant no revisado en una nueva herramienta de escritura MCP. La nueva funcionalidad debe revisarse, implementarse como herramientas tipadas, probarse y publicarse a través de Git.

Diagnósticos opcionales de host y LAN

El recolector systemd bajo collector/ no tiene listener y no acepta ningún comando, ruta, contenedor, expresión de registro o URL seleccionado por el llamante. Publica instantáneas y libros de contabilidad acotados y saneados en un directorio fijo. El contenedor MCP recibe solo ese directorio como montaje de solo lectura—nunca el socket de Docker, el journal del host, procfs, sysfs o el control de systemd.

Las herramientas LAN operan solo dentro de una /24 configurada, devuelven ID de nodo opacos, usan una lista de permitidos de servicios TCP cerrada, no envían carga útil de aplicación y omiten direcciones sin procesar. No pueden escanear redes arbitrarias ni controlar dispositivos.

Consulte docs/operations.md y collector/README.md para el modelo de datos completo, límites de retención, implementación, verificación, incidentes y procedimientos de reversión.

Modelo de seguridad

Este servidor es intencionadamente más limitado que la API de Home Assistant:

• Sin ejecución de shell, paso arbitrario de WebSocket, archivos arbitrarios, registros sin procesar, administración de Docker, reinicio de servicios, apagado, recuperación de credenciales, imágenes de cámaras ni desactivación de alarmas.

• Las llamadas genéricas a servicios de Home Assistant están permitidas por dominio y servicio; se prefieren herramientas tipadas dedicadas.

• Las entradas se validan mediante esquema, los tamaños de los resultados están acotados y los campos de diagnóstico sensibles se redactan de forma recursiva.

• Las operaciones destructivas o físicas utilizan anotaciones explícitas y compuertas de confirmación.

• Los registros de auditoría contienen nombres de herramientas y metadatos acotados, no credenciales ni evidencia de diagnóstico devuelta.

• El contenedor se ejecuta como un usuario sin privilegios con un sistema de archivos de solo lectura, todas las capacidades de Linux eliminadas y no-new-privileges habilitado.

• La auditoría de publicación pública examina tanto el árbol actual como el historial de Git antes de la publicación.

Nunca utilice un termostato, luz, cerradura, aspirador, aspersor, cámara, altavoz, televisor, copia de seguridad, notificación u otro efecto físico secundario como prueba de conectividad.

Para el informe de vulnerabilidades y el manejo de información de despliegue sensible, lea SECURITY.md.

Despliegue y verificación

El script de despliegue de PowerShell en scripts/deploy-production.ps1 es una referencia opinada de AWS Lightsail. Requiere parámetros explícitos de perfil de AWS, región, instancia, URL de frontend y URL de MCP; empaqueta el código fuente revisado; crea copias de seguridad; despliega el recopilador y el contenedor; ejecuta la verificación; y admite la reversión. Revíselo detenidamente antes de adaptarlo a otro host.

Antes de cada publicación pública o lanzamiento de producción:

uv sync --frozen
uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

Luego verifique, sin cambiar el estado del dispositivo:

1. /healthz funciona localmente y a través del borde público.

2. Las solicitudes MCP no autenticadas y con token no válido son rechazadas.

3. El descubrimiento autenticado informa la versión esperada y el número de herramientas.

4. Las comprobaciones de solo lectura de visión general, sincronización de capacidades, rutas e integraciones se realizan correctamente.

5. El commit público de Git, el artefacto desplegado y la versión del servicio informada son idénticos.

Los procedimientos de producción y las compuertas de reversión se detallan en docs/operations.md.

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas cuando preservan el modelo de seguridad acotado del proyecto.

Para nuevas herramientas:

1. Prefiera una operación tipada y limitada en lugar de un paso genérico.

2. Defina con precisión las anotaciones de solo lectura, idempotentes, de escritura o destructivas.

3. Valide los dominios de entidades, enumeraciones, longitudes, ventanas de tiempo y límites de resultados.

4. Exija confirmación explícita para acciones físicas o administrativas de gran repercusión.

5. Añada pruebas de autorización, de ruta negativa, de redacción y de regresión.

6. Actualice la documentación de capacidades y ejecute la auditoría de historial público.

No incluya configuración doméstica real, URL privadas, credenciales, registros, tokens, horarios, topología ni respuestas de proveedores en una incidencia, fixture, captura de pantalla, commit o solicitud de extracción.

Licencia

Actualmente no se incluye ninguna licencia de código abierto. La visibilidad pública no otorga permiso para copiar, modificar o redistribuir el código. Los propietarios del repositorio deben añadir una licencia explícita antes de aceptar la reutilización o redistribución.

Referencias

• Model Context Protocol

• OpenAI: Build an MCP server

• OpenAI: Authenticate users

• Cloudflare Tunnel monitoring

• Cloudflare Tunnel metrics