Hass-MCP

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

Descripción general

Hass-MCP permite que los asistentes de IA como Claude interactúen directamente con su instancia de Home Assistant, lo que les permite:

• Consultar el estado de dispositivos y sensores
• Controlar luces, interruptores y otras entidades
• Obtenga resúmenes de su 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 : obtenga información de alto nivel sobre los tipos de entidad
• Soporte de automatización : enumerar y controlar automatizaciones
• Conversaciones guiadas : utilice indicaciones para tareas comunes, como la creación de automatizaciones.
• Búsqueda inteligente : busque entidades por nombre, tipo o estado
• Eficiencia de tokens : respuestas JSON optimizadas para minimizar el uso de tokens

Instalación

Prerrequisitos

• Instancia de Home Assistant con token de acceso de larga duración
• Uno de los siguientes:
  • Docker (recomendado)
  • Python 3.13+ y uv

Configuración con Claude Desktop

Instalación de Docker (recomendada)

1. Extraiga la imagen de Docker:
   docker pull voska/hass-mcp:latest
2. Agregue el servidor MCP a Claude Desktop:a. Abra Claude Desktop y vaya a Configuración. b. Vaya a Desarrollador > Editar configuración. c. Agregue la siguiente configuración a su 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. Reemplace YOUR_LONG_LIVED_TOKEN con su token de acceso de larga duración de Home Assistant. e. Actualice HA_URL :
   • Si ejecuta Home Assistant en la misma máquina: use http://host.docker.internal:8123 (Docker Desktop en Mac/Windows)
   • Si ejecuta Home Assistant en otra máquina: use la IP o el nombre de host real

   f. Guarde el archivo y reinicie Claude Desktop.

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

Nota : Si ejecuta Home Assistant en Docker en la misma máquina, es posible que deba agregar --network host a los argumentos de Docker para que el contenedor acceda a Home Assistant. Como alternativa, use la dirección IP de su máquina en lugar de host.docker.internal .

Otros clientes de MCP

Cursor

1. Vaya a Configuración del cursor > MCP > Agregar nuevo servidor MCP
2. Rellene el formulario:
   • Nombre: Hass-MCP
   • Tipo: command
   • Dominio:
     docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
   • Reemplace YOUR_LONG_LIVED_TOKEN con su token de Home Assistant real
   • Actualice HA_URL para que coincida con la dirección de su instancia de Home Assistant
3. Haga clic en "Agregar" para guardar

Código Claude (CLI)

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

Usando Docker (recomendado):

Reemplace YOUR_LONG_LIVED_TOKEN con su token de Home Assistant real y actualice HA_URL para que coincida con la dirección de su instancia de Home Assistant.

Ejemplos de uso

A continuación se muestran algunos ejemplos de indicaciones que puede utilizar con Claude una vez configurado Hass-MCP:

• "¿Cuál es el estado actual de las luces de mi sala de estar?"
• "Apaga todas las luces de la cocina"
• "Enumerar todos mis sensores que contienen datos de temperatura"
• "Dame un resumen de mis entidades climáticas"
• "Crea una automatización que encienda las luces al atardecer"
• "Ayúdenme a solucionar el problema de por qué el sensor de movimiento de mi habitación no funciona"
• "Buscar entidades relacionadas con mi sala de estar"

Herramientas disponibles

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

• get_version : Obtener la versión de Home Assistant
• get_entity : obtiene el estado de una entidad específica con filtrado de campo opcional
• entity_action : Realizar acciones sobre las entidades (activar, desactivar, alternar)
• list_entities : obtiene una lista de entidades con filtrado de dominio y búsqueda opcionales
• search_entities_tool : busca 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 : Llama a cualquier servicio de Home Assistant
• restart_ha : Reiniciar Home Assistant
• get_history : Obtener el historial de estado de una entidad
• get_error_log : Obtener el registro de errores de Home Assistant

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 activador
• debug_automation : Ayuda para la resolución de problemas de automatizaciones que no funcionan
• troubleshoot_entity : diagnosticar problemas con entidades
• routine_optimizer : analiza patrones de uso y sugiere rutinas optimizadas según el comportamiento real
• automation_health_check : Revisar todas las automatizaciones, encontrar conflictos, redundancias u oportunidades de mejora
• entity_naming_consistency : audita los nombres de las entidades y sugiere mejoras de estandarización
• dashboard_layout_generator : Crea 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 : Obtenga información detallada sobre una entidad con todos los atributos
• hass://entities : enumera 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} : busca entidades que coincidan con una consulta con un límite de resultados personalizado

Desarrollo

Ejecución de pruebas

Licencia

Licencia MIT