Ambient Home Assistant MCP

Ambient Home Assistant MCP es un puente semántico y seguro que proporciona a ChatGPT y otros clientes MCP un acceso específico a Home Assistant. Es la base de servidor para la futura aplicación Ambient Home Assistant orientada al usuario.

Estado de la Fase 2: local/privado y de solo lectura. Esta versión añade descubrimiento semántico de entidades, estado actual, áreas, plantas y resúmenes de dominios. No puede controlar dispositivos ni cambiar Home Assistant.

Qué es—y qué no es

El puente es una capa de abstracción y seguridad. Con el tiempo, puede elegir entre las interfaces REST, WebSocket y MCP/Assist nativas de Home Assistant mientras presenta herramientas pequeñas y semánticas al modelo.

No es:

• un reemplazo de Home Assistant;

• una API de administración de Home Assistant sin restricciones;

• un envoltorio de API genérico expuesto a un LLM; o

• un proxy inverso para el endpoint /api/mcp de Home Assistant.

Related MCP server: ha-ai-learner

Arquitectura

flowchart TD
    C[ChatGPT or MCP client] -->|MCP| A[Ambient Home Assistant MCP]
    A --> T[Semantic tools]
    A --> P[Policy and security]
    A --> N[Normalized data and diagnostics]
    T --> H[Home Assistant client facade]
    P --> H
    N --> H
    H --> R[REST state API]
    H --> W[WebSocket registries]
    H -. selective future use .-> M[HA MCP or Assist API]

Las herramientas MCP nunca realizan solicitudes HTTP sin procesar. Dependen de HomeAssistantClient, que gestiona la selección de interfaz y normaliza inmediatamente las respuestas ascendentes. Consulte el registro de decisiones de arquitectura.

Capacidades

No se implementan llamadas de servicio, cambios de estado ni endpoints administrativos.

Modelo de seguridad

• Los tokens de Home Assistant provienen solo de la configuración en tiempo de ejecución y utilizan tipos secretos de Pydantic.

• Los registros están estructurados y redactan tokens de portador y campos comunes de credenciales.

• Los datos sin procesar de /api/config se reducen a un modelo en lista blanca antes de que puedan llegar a un resultado de herramienta.

• Los atributos detallados de entidad utilizan una lista blanca explícita y excluyen URL, fuentes de cámara, tokens, credenciales, coordenadas y metadatos con información de ubicación.

• Los estados actuales nunca se almacenan en caché. Los metadatos del registro utilizan una caché TTL limitada de 60 segundos para evitar autenticaciones WebSocket repetidas y lecturas de registro.

• Las listas blancas de Host y Origin del transporte MCP protegen contra el rebinding de DNS.

• El motor de políticas permite lecturas y falla cerrado para cada clase de control.

• El contenedor se ejecuta como un usuario no root con un sistema de archivos de solo lectura en Compose.

Nunca confirme .env, tokens de Home Assistant, credenciales, URL privadas o certificados. Consulte Seguridad antes de cualquier trabajo de implementación.

Inicio rápido

Requisitos: Python 3.12+ y uv.

cp .env.example .env
# Edit .env and provide HOME_ASSISTANT_URL and HOME_ASSISTANT_TOKEN.
uv sync --all-extras
uv run ambient-ha-mcp

El endpoint MCP HTTP Streamable es http://127.0.0.1:8000/mcp; la salud está en http://127.0.0.1:8000/health.

Inspeccione las herramientas localmente:

npx @modelcontextprotocol/inspector@latest

Luego conecte el Inspector a http://127.0.0.1:8000/mcp.

Comandos de desarrollo

uv sync --all-extras          # install
uv run ambient-ha-mcp         # run locally
uv run pytest                 # unit tests; real HA tests skip by default
uv run ruff check .           # lint
uv run ruff format --check .  # formatting check
uv run mypy                   # type check
docker build -t ambient-ha-mcp .
docker compose up --build

Regenere el bloqueo de dependencias después de un cambio intencional de dependencia:

uv lock

Docker Compose

Copie .env.example a .env, proporcione los dos ajustes requeridos de Home Assistant y ejecute docker compose up --build. Compose publica solo en loopback del host.

La sonda de salud de Docker prueba la actividad de la aplicación. Una interrupción temporal de Home Assistant cambia /health a status: degraded, pero deja el estado HTTP 200 para que el orquestador no reinicie un puente saludable en un bucle.

Documentación

• Arquitectura

• Seguridad

• Contratos de herramientas

• Desarrollo

• Configuración de ChatGPT y limitaciones actuales

Licencia

MIT. Consulte LICENSE.