hass-mcp — Edición HiTech Lab

Mantenido y optimizado por HiTech Lab Fuente: https://github.com/voska/hass-mcp

Hass-MCP

Un servidor de Model Context Protocol (MCP) para la integración de Home Assistant con Claude y otros LLM.

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

Related MCP server: Hass-MCP

Capturas de pantalla

Características

• Gestión de entidades: Obtén estados, controla dispositivos y busca entidades

• Resúmenes por dominio: Obtén información de alto nivel sobre tipos de entidades

• Soporte de automatizaciones: Lista y controla automatizaciones

• Conversaciones guiadas: Usa prompts para tareas comunes como crear automatizaciones

• Búsqueda inteligente: Encuentra entidades por nombre, tipo o estado

• Edición de paneles en vivo: Lee y edita paneles de Lovelace (tarjetas y vistas) a través de la API WebSocket de Home Assistant — los cambios aparecen al instante en los navegadores abiertos, con copias de seguridad automáticas y una vista previa de simulación

• Eficiencia de tokens: Respuestas JSON optimizadas 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)

1. Descarga la imagen de Docker:

   docker pull voska/hass-mcp:latest

2. Añade el servidor MCP a Claude Desktop:

   a. Abre Claude Desktop y ve a Configuración b. Navega a Desarrollador > Editar configuración c. Añade 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 la 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

3. La herramienta "Hass-MCP" debería aparecer ahora en el menú de herramientas de Claude Desktop

Nota: Si ejecutas Home Assistant en Docker en la misma máquina, es posible que necesites añadir --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

1. Instala uv en tu sistema.

2. Añade el servidor MCP a Claude Desktop:

   a. Abre Claude Desktop y ve a Configuración b. Navega a Desarrollador > Editar configuración c. Añade 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 la 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

3. La herramienta "Hass-MCP" debería aparecer ahora en el menú de herramientas de Claude Desktop

Otros clientes MCP

Cursor

1. Ve a Configuración de Cursor > MCP > Añadir nuevo servidor MCP

2. Rellena 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 HA_URL para que coincida con la dirección de tu instancia de Home Assistant

3. Haz clic en "Añadir" para guardar

Claude Code (CLI)

Para usar con la CLI de Claude Code, puedes añadir el servidor MCP directamente con 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 HA_URL para que coincida con la dirección de tu instancia de Home Assistant.

Transporte HTTP (transmisible)

Para despliegues que no pueden usar stdio — ejecutándose detrás de una pasarela MCP, alojado en Smithery, compartiendo un servidor entre varios clientes, o conectándose desde herramientas basadas en red como LibreChat o OpenWebUI — Hass-MCP soporta 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. Cualquiera 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 una de las siguientes opciones:

• Un proxy inverso (nginx, Caddy, Traefik) que valide autenticación básica o tokens bearer

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

• Vinculación solo a localhost (el valor predeterminado — cambia --host solo si sabes lo que haces)

No expongas :8000 a Internet abierta 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 por defecto. Sobrescribe con --host 0.0.0.0 solo cuando también hayas configurado autenticación delante de é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 obligatorio dentro de Docker para que el puerto sea accesible a través del bridge. 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.

Endpoint

El endpoint MCP está en /mcp. Apunta tu cliente a http://<host>:<puerto>/mcp.

Smithery / PaaS

El servidor respeta la variable de entorno PORT (la convención de Smithery) además de MCP_PORT. El despliegue en 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 runtime en sandbox): 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á definido. verify=False no se admite intencionalmente — usa HA_URL=http://... si realmente quieres tráfico LAN local sin cifrar.

Ejemplos de uso

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

• "¿Cuál es el estado actual de las luces de mi salón?"

• "Apaga todas las luces de la cocina"

• "¿Cuál es la temperatura en el dormitorio principal?"

• "Enumera todo lo que hay en la habitación de invitados"

• "Enumera todos mis sensores que contengan 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 salón"

• "Muéstrame las últimas 50 líneas de ERROR del registro de Home Assistant"

• "¿Qué ha estado fallando hoy en la integración mqtt?"

• "Muéstrame el uso de energía por día del último mes"

• "¿Qué pasó con el sensor de la puerta principal el martes pasado?"

Herramientas disponibles

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

• get_version: Obtén la versión de Home Assistant

• get_entity: Obtén el estado de una entidad específica con filtrado de campos opcional

• entity_action: Realiza acciones en entidades (encender, apagar, alternar)

• list_entities: Obtén una lista de entidades con filtrado por dominio y búsqueda opcionales

• search_entities_tool: Busca entidades que coincidan con una consulta

• domain_summary_tool: Obtén un resumen de las entidades de un dominio

• list_automations: Obtén una lista de todas las automatizaciones

• call_service_tool: Llama a cualquier servicio de Home Assistant

• restart_ha: Reinicia Home Assistant

• get_history: Obtén el historial de estados de una entidad (últimas N horas)

• get_history_range: Obtén el historial de cambios de estado de una entidad en un intervalo de fecha/hora explícito (start_time / end_time, ISO-8601)

• get_statistics: Obtén estadísticas agregadas a largo plazo (media / mín / máx por intervalo) para una entidad en las últimas N horas — funciona para datos más antiguos que la ventana de retención a corto plazo del recorder

• get_statistics_range: Igual, pero para un intervalo de fecha/hora explícito — útil para consultas de tendencias mensuales / anuales

• get_error_log: Obtén el registro de errores de Home Assistant, con filtros opcionales de level / integration / search_term / lines aplicados en el servidor para que los registros ruidosos no saturen el contexto de Claude

• get_entities_by_area: Enumera las 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 todos los navegadores abiertos al instante — sin reinicio.

• list_dashboards: Enumera los paneles (el predeterminado más cualquier panel de usuario), cada uno con su url_path y mode (storage / yaml)

• get_dashboard_config: Obtén la configuración completa de un panel

• set_dashboard_config: Reemplaza la configuración completa de un panel (bajo nivel)

• add_card / update_card / remove_card / move_card: Edita tarjetas dentro de una vista (la vista se selecciona por índice, o por su path / title)

• list_view_sections: Enumera las secciones de una vista de tipo "sections"

• add_view / remove_view / update_view: Edita las vistas de un panel

• list_dashboard_backups / restore_dashboard: Enumera y revierte 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 única 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 una section se rechazan con la lista de secciones disponibles — en lugar de guardar silenciosamente una tarjeta donde nunca se mostrarí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 storage. Solo se pueden editar los paneles gestionados por la interfaz ("storage"). Los paneles en modo YAML se detectan y se 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 se encargan de esto por ti.

• Copias de seguridad automáticas. Antes de cada escritura, la configuración actual se guarda en HASS_MCP_BACKUP_DIR (por defecto ~/.hass-mcp/dashboard-backups/). Cuando se ejecuta en Docker, monta un volumen en esta ruta o las copias de seguridad se perderán cuando el contenedor se recree.

Prompts para conversaciones guiadas

Hass-MCP incluye varios prompts 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 según 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 endpoints 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 sus 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