Servidor MCP de Home Assistant | Awesome MCP Servers

Hass-MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración de Home Assistant con Claude y otros LLMs.

Descripción general

Hass-MCP permite que asistentes de IA como Claude interactúen directamente con tu instancia de Home Assistant, permitiéndoles:

Consultar el estado de dispositivos y sensores
Controlar luces, interruptores y otras entidades
Obtener resúmenes de tu hogar inteligente
Solucionar problemas de automatizaciones y entidades
Buscar entidades específicas
Crear conversaciones guiadas para tareas comunes

Capturas de pantalla

Características

Gestión de entidades: Obtener estados, controlar dispositivos y buscar entidades
Resúmenes de dominio: Obtener información de alto nivel sobre tipos de entidades
Soporte de automatizaciones: Listar y controlar automatizaciones
Conversaciones guiadas: Usar indicaciones para tareas comunes como crear automatizaciones
Búsqueda inteligente: Encontrar entidades por nombre, tipo o estado
Edición de paneles en vivo: Leer y editar paneles de Lovelace (tarjetas y vistas) a través de la API WebSocket de Home Assistant — los cambios aparecen instantáneamente en los navegadores abiertos, con copias de seguridad automáticas y una vista previa de simulación
Eficiencia de tokens: Respuestas JSON concisas para minimizar el uso de tokens

Instalación

Requisitos previos

Instancia de Home Assistant con token de acceso de larga duración
Una de las siguientes opciones:
- Docker (recomendado)
- Python 3.13+ y uv

Configuración con Claude Desktop

Instalación con Docker (recomendada)

Extrae la imagen de Docker:
```
docker pull voska/hass-mcp:latest
```
Agrega el servidor MCP a Claude Desktop:

a. Abre Claude Desktop y ve a Configuración b. Navega a Desarrollador > Editar configuración c. Agrega la siguiente configuración a tu archivo claude_desktop_config.json:
```
{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}
```
d. Reemplaza YOUR_LONG_LIVED_TOKEN con tu token de acceso de larga duración real de Home Assistant e. Actualiza el HA_URL:
- Si ejecutas Home Assistant en la misma máquina: usa http://host.docker.internal:8123 (Docker Desktop en Mac/Windows)
- Si ejecutas Home Assistant en otra máquina: usa la IP o el nombre de host real
f. Guarda el archivo y reinicia Claude Desktop
La herramienta "Hass-MCP" debería aparecer ahora en tu menú de herramientas de Claude Desktop

Nota: Si ejecutas Home Assistant en Docker en la misma máquina, es posible que necesites agregar --network host a los argumentos de Docker para que el contenedor pueda acceder a Home Assistant. Alternativamente, usa la dirección IP de tu máquina en lugar de host.docker.internal.

uv/uvx

Instala uv en tu sistema.
Agrega el servidor MCP a Claude Desktop:

a. Abre Claude Desktop y ve a Configuración b. Navega a Desarrollador > Editar configuración c. Agrega la siguiente configuración a tu archivo claude_desktop_config.json:
```
{
  "mcpServers": {
    "hass-mcp": {
      "command": "uvx",
      "args": ["hass-mcp"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}
```
d. Reemplaza YOUR_LONG_LIVED_TOKEN con tu token de acceso de larga duración real de Home Assistant e. Actualiza el HA_URL:
- Si ejecutas Home Assistant en la misma máquina: usa http://host.docker.internal:8123 (Docker Desktop en Mac/Windows)
- Si ejecutas Home Assistant en otra máquina: usa la IP o el nombre de host real
f. Guarda el archivo y reinicia Claude Desktop
La herramienta "Hass-MCP" debería aparecer ahora en tu menú de herramientas de Claude Desktop

Otros clientes MCP

Cursor

Ve a Configuración de Cursor > MCP > Agregar nuevo servidor MCP
Completa el formulario:
- Nombre: Hass-MCP
- Tipo: command
- Comando:
```
docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
```
- Reemplaza YOUR_LONG_LIVED_TOKEN con tu token real de Home Assistant
- Actualiza la URL_HA para que coincida con la dirección de tu instancia de Home Assistant
Haz clic en "Agregar" para guardar

Claude Code (CLI)

Para usar con Claude Code CLI, puedes agregar el servidor MCP directamente usando el comando mcp add:

Usando Docker (recomendado):

claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

Reemplaza YOUR_LONG_LIVED_TOKEN con tu token real de Home Assistant y actualiza la URL_HA para que coincida con la dirección de tu instancia de Home Assistant.

Transporte HTTP (transmisible)

Para implementaciones que no pueden usar stdio — ejecutándose detrás de una puerta de enlace MCP, alojado en Smithery, compartiendo un servidor entre múltiples clientes, o conectándose desde herramientas basadas en red como LibreChat o OpenWebUI — Hass-MCP admite el transporte HTTP transmisible de MCP. El servidor se ejecuta en modo sin estado (sin Mcp-Session-Id, respuestas JSON), adecuado para hosts escalados horizontalmente.

[!PRECAUCIÓN] El modo HTTP expone el control completo de Home Assistant a través de la red. Cualquier persona que pueda alcanzar el puerto puede llamar a cualquier herramienta — apagar luces, desbloquear puertas, activar automatizaciones, reiniciar HA. La especificación MCP aún no incluye una capa de autenticación integrada en este servidor. Hasta que lo haga, debes colocarlo detrás de uno de los siguientes:

Un proxy inverso (nginx, Caddy, Traefik) que realice autenticación básica o validación de token portador

Una VPN o red de confianza cero (Tailscale, WireGuard, Cloudflare Access)

Solo enlace de localhost (el predeterminado — cambia --host solo si sabes lo que estás haciendo)

No expongas :8000 a Internet abierto sin autenticación.

Ejecución local

Usando uvx:

HA_URL=http://homeassistant.local:8123 \
HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
uvx hass-mcp --http --port 8000

El servidor se vincula a 127.0.0.1 de forma predeterminada. Anula con --host 0.0.0.0 solo cuando también hayas configurado autenticación frente a él.

Ejecución en Docker

docker run --rm -p 8000:8000 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000

--host 0.0.0.0 es necesario dentro de Docker para que el puerto sea accesible a través del puente. Vincula la publicación (-p) a 127.0.0.1:8000:8000 si solo quieres que sea accesible desde el host, o coloca un proxy inverso delante.

Punto final

El punto final MCP está en /mcp. Apunta tu cliente a http://<host>:<port>/mcp.

Smithery / PaaS

El servidor respeta la variable de entorno PORT (convención de Smithery) además de MCP_PORT. La implementación de Smithery requiere el modo --http y lee PORT automáticamente.

CA personalizada / privada

Si tu instancia de Home Assistant sirve un certificado firmado por tu propia CA (step-ca, smallstep, OpenSSL de homelab), hass-mcp puede verificarlo sin deshabilitar TLS:

Localmente: instala la raíz de la CA en el almacén de confianza de tu sistema operativo (Llavero de macOS, Almacén de certificados de Windows, o update-ca-certificates en Linux). hass-mcp lo detecta automáticamente a través de truststore.
En Docker (o cualquier entorno de ejecución en espacio aislado): monta el archivo de la CA y apunta SSL_CERT_FILE a él.

docker run --rm \
  -v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
  -e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
  -e HA_URL=https://homeassistant.example.internal:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest

SSL_CERT_FILE siempre tiene prioridad sobre el almacén del sistema operativo cuando está configurado. verify=False no se admite intencionalmente — usa HA_URL=http://... si realmente deseas tráfico LAN local sin cifrar.

Ejemplos de uso

Aquí hay algunos ejemplos de indicaciones que puedes usar con Claude una vez que Hass-MCP esté configurado:

"¿Cuál es el estado actual de las luces de mi sala de estar?"
"Apaga todas las luces de la cocina"
"¿Cuál es la temperatura en el dormitorio principal?"
"Enumera todo en la habitación de invitados"
"Enumera todos mis sensores que contienen datos de temperatura"
"Dame un resumen de mis entidades de clima"
"Crea una automatización que encienda las luces al atardecer"
"Ayúdame a solucionar por qué mi automatización del sensor de movimiento del dormitorio no funciona"
"Busca entidades relacionadas con mi sala de estar"
"Muéstrame las últimas 50 líneas de ERROR del registro de Home Assistant"
"¿Qué ha estado fallando en la integración de mqtt hoy?"
"Muéstrame el uso de energía por día durante el último mes"
"¿Qué sucedió con el sensor de la puerta principal el martes pasado?"

Herramientas disponibles

Hass-MCP proporciona varias herramientas para interactuar con Home Assistant:

get_version: Obtener la versión de Home Assistant
get_entity: Obtener el estado de una entidad específica con filtrado de campos opcional
entity_action: Realizar acciones en entidades (encender, apagar, alternar)
list_entities: Obtener una lista de entidades con filtrado de dominio opcional y búsqueda
search_entities_tool: Buscar entidades que coincidan con una consulta
domain_summary_tool: Obtener un resumen de las entidades de un dominio
list_automations: Obtener una lista de todas las automatizaciones
call_service_tool: Llamar a cualquier servicio de Home Assistant
restart_ha: Reiniciar Home Assistant
get_history: Obtener el historial de estados de una entidad (últimas N horas)
get_history_range: Obtener el historial de cambios de estado de una entidad en un rango de fecha/hora explícito (start_time / end_time, ISO-8601)
get_statistics: Obtener estadísticas agregadas a largo plazo (media / mín / máx por intervalo) para una entidad durante las últimas N horas — funciona para datos más antiguos que la ventana de retención a corto plazo del registrador
get_statistics_range: Igual, pero para un rango de fecha/hora explícito — útil para consultas de tendencias mensuales / anuales
get_error_log: Obtener el registro de errores de Home Assistant, con filtros opcionales level / integration / search_term / lines aplicados en el servidor para que los registros ruidosos no agoten el contexto de Claude
get_entities_by_area: Listar entidades en un área / habitación específica

Edición de paneles (Lovelace)

Lee y edita paneles en vivo a través de la API WebSocket de Home Assistant. Guardar envía el cambio a cada navegador abierto instantáneamente — sin reinicio.

list_dashboards: Listar paneles (el predeterminado más cualquier panel de usuario), cada uno con su url_path y mode (storage / yaml)
get_dashboard_config: Obtener la configuración completa de un panel
set_dashboard_config: Reemplazar la configuración completa de un panel (bajo nivel)
add_card / update_card / remove_card / move_card: Editar tarjetas dentro de una vista (la vista se selecciona por índice, o por su path / title)
list_view_sections: Listar las secciones de una vista de tipo "secciones"
add_view / remove_view / update_view: Editar las vistas de un panel
list_dashboard_backups / restore_dashboard: Listar y revertir a las copias de seguridad automáticas previas al guardado

Vistas de secciones: El tipo de vista moderno de Home Assistant (type: sections) almacena sus tarjetas dentro de secciones en lugar de una sola lista de nivel superior. Para esas vistas, llama a list_view_sections y pasa el argumento section (índice, título o encabezado) a las herramientas de tarjetas. Las ediciones de tarjetas en una vista de secciones sin un section se rechazan con la lista de secciones disponibles — en lugar de guardar silenciosamente una tarjeta donde nunca se renderizaría.

Cada herramienta de edición acepta dry_run=true para previsualizar la configuración resultante y un resumen de cambios sin guardar.

Notas importantes:

Se requiere token de administrador. Guardar la configuración de Lovelace requiere que el token de larga duración pertenezca a un usuario administrador.
Solo modo de almacenamiento. Solo se pueden editar los paneles gestionados por la interfaz de usuario ("almacenamiento"). Los paneles en modo YAML se detectan y rechazan con un mensaje claro — edita sus archivos YAML directamente en su lugar.
Escrituras de configuración completa. Home Assistant no tiene una API de edición parcial; cada cambio es una lectura-modificación-escritura de todo el panel. Las herramientas de tarjetas/vistas de alto nivel manejan esto por ti.
Copias de seguridad automáticas. Antes de cada escritura, la configuración actual se guarda en HASS_MCP_BACKUP_DIR (predeterminado ~/.hass-mcp/dashboard-backups/). Cuando se ejecuta en Docker, monta un volumen en esta ruta o las copias de seguridad se pierden cuando se recrea el contenedor.

Indicaciones para conversaciones guiadas

Hass-MCP incluye varias indicaciones para conversaciones guiadas:

create_automation: Guía para crear automatizaciones de Home Assistant según el tipo de disparador
debug_automation: Ayuda para solucionar problemas de automatizaciones que no funcionan
troubleshoot_entity: Diagnosticar problemas con entidades
routine_optimizer: Analizar patrones de uso y sugerir rutinas optimizadas basadas en el comportamiento real
automation_health_check: Revisar todas las automatizaciones, encontrar conflictos, redundancias u oportunidades de mejora
entity_naming_consistency: Auditar nombres de entidades y sugerir mejoras de estandarización
dashboard_layout_generator: Crear paneles optimizados según las preferencias del usuario y los patrones de uso

Recursos disponibles

Hass-MCP proporciona los siguientes puntos finales de recursos:

hass://entities/{entity_id}: Obtener el estado de una entidad específica
hass://entities/{entity_id}/detailed: Obtener información detallada sobre una entidad con todos los atributos
hass://entities: Listar todas las entidades de Home Assistant agrupadas por dominio
hass://entities/domain/{domain}: Obtener una lista de entidades para un dominio específico
hass://search/{query}/{limit}: Buscar entidades que coincidan con una consulta con un límite de resultados personalizado

Desarrollo

Ejecución de pruebas

uv run pytest tests/

Licencia

MIT License

Home Assistant

Documentación