Home Assistant MCP

Una integración MCP para controlar dispositivos de Home Assistant con asistentes de IA.

Documentación

Home Assistant MCP

Una integración del Model Context Protocol (MCP) para controlar dispositivos de Home Assistant mediante asistentes de IA.

Descripción general

Este MCP permite a los asistentes de IA controlar tus dispositivos de Home Assistant. Proporciona herramientas para:

Buscar entidades en tu instancia de Home Assistant
Controlar dispositivos (encenderlos/apagarlos)
Controlar colores y brillo de las luces

Requisitos previos

Python 3.11 o superior
Instancia de Home Assistant en ejecución y accesible mediante API
Token de acceso de larga duración de Home Assistant

Instalación

Instalación mediante Smithery

Para instalar automáticamente la integración de Home Assistant para Claude Desktop mediante Smithery:

npx -y @smithery/cli install @hpohlmann/home-assistant-mcp --client claude

Instalación manual

Clona este repositorio
Configura un entorno de Python:

cd home-assistant
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -U pip
pip install uv
uv pip install -e .

Configuración

Obtener un token de acceso de larga duración de Home Assistant

Ve a tu instancia de Home Assistant
Navega hasta tu perfil (haz clic en tu nombre de usuario en la barra lateral)
Desplázate hacia abajo hasta "Long-Lived Access Tokens"
Crea un nuevo token con un nombre descriptivo como "MCP Integration"
Copia el token (solo lo verás una vez)

Configuración en Cursor AI

Añade la siguiente configuración a tu configuración de MCP en Cursor:

{
  "mcpServers": {
    "home_assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/home-assistant-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "HOME_ASSISTANT_TOKEN": "your_home_assistant_token_here"
      },
      "inheritEnv": true
    }
  }
}

Reemplaza:

/path/to/your/home-assistant con la ruta real a este directorio
your_home_assistant_token_here con tu token de acceso de larga duración de Home Assistant

Configuración de la URL de Home Assistant

Por defecto, el MCP intenta conectarse a Home Assistant en http://homeassistant.local:8123.

Si tu Home Assistant está en una URL diferente, puedes modificar la variable HA_URL en app/config.py.

Uso

Una vez configurado, puedes usar Cursor AI para controlar tus dispositivos de Home Assistant:

Buscar dispositivos: "Encuentra las luces de mi sala de estar"
Controlar dispositivos: "Enciende la luz de la cocina"
Controlar colores de luces: "Pon las luces de mi sala de estar en rojo"
Ajustar el brillo: "Pon las luces de mi comedor en azul al 50% de brillo"

Funciones de control de luces

El MCP ahora admite capacidades avanzadas de control de luces:

Control de color: Establece cualquier color RGB para luces compatibles
- Especifica colores usando valores RGB (0-255 para cada componente)
- Ejemplo: set_device_color("light.living_room", 255, 0, 0) para rojo
Control de brillo: Ajusta el brillo de las luces
- Parámetro de brillo opcional (0-255)
- Se puede combinar con cambios de color
- Ejemplo: set_device_color("light.dining_room", 0, 0, 255, brightness=128) para azul de brillo medio

Solución de problemas

Si recibes errores de autenticación, verifica que tu token sea correcto y no haya caducado
Comprueba que tu instancia de Home Assistant sea accesible en la URL configurada
Para problemas de control de color:
- Verifica que tu entidad de luz admita control de color RGB
- Comprueba que la luz esté encendida antes de intentar cambiar los colores

Capacidades futuras

Exposición dinámica de entidades

La implementación actual requiere un proceso de dos pasos para controlar dispositivos:

Buscar entidades mediante lenguaje natural
Controlar la entidad usando su entity_id específico

Una mejora planificada es crear una forma más dinámica de exponer entidades a la herramienta de control de dispositivos, permitiendo que la IA:

Controle dispositivos directamente mediante comandos más naturales (p. ej., "apaga las luces de la cocina")
Almacene en caché las entidades de uso frecuente para un acceso más rápido
Admite operaciones más complejas como ajustar el brillo, la temperatura u otros atributos
Maneje grupos de entidades y escenas de forma más intuitiva

Esto reduciría significativamente el tiempo de acción y crearía una experiencia de usuario más fluida al controlar dispositivos de Home Assistant mediante un asistente de IA.