Skip to main content
Glama
Home Assistant MCP

Home Assistant MCP

by hpohlmann

Asistente de hogar MCP

Una integración del Protocolo de Contexto de Modelo (MCP) para controlar dispositivos Home Assistant mediante asistentes de IA.

Descripción general

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

  1. Buscar entidades en su instancia de Home Assistant

  2. Dispositivos de control (encenderlos/apagarlos)

  3. Controlar los colores y el brillo de la luz

Related MCP server: Hass-MCP

Prerrequisitos

  • Python 3.11 o superior

  • Instancia de Home Assistant en ejecución y accesible a través de API

  • Token de acceso de larga duración de Home Assistant

Instalación

  1. Clonar este repositorio

  2. Configurar 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

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

  1. Vaya a su instancia de Home Assistant

  2. Navega a tu perfil (haz clic en tu nombre de usuario en la barra lateral)

  3. Desplácese hacia abajo hasta "Tokens de acceso de larga duración".

  4. Cree un nuevo token con un nombre descriptivo como "Integración MCP".

  5. Copia el token (solo lo verás una vez)

Configurar en Cursor AI

Agregue la siguiente configuración a su 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
    }
  }
}

Reemplazar:

  • /path/to/your/home-assistant con la ruta real a este directorio

  • your_home_assistant_token_here con su token de acceso de larga duración de Home Assistant

Configuración de URL de Home Assistant

De forma predeterminada, el MCP intenta conectarse a Home Assistant en http://homeassistant.local:8123 .

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

Uso

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

  • Buscar dispositivos: "Buscar las luces de mi salón"

  • Dispositivos de control: "Enciende la luz de la cocina"

  • Controlar los colores de la luz: "Pon las luces de mi sala en rojo"

  • Ajustar el brillo: "Configurar las luces de mi comedor en azul con un brillo del 50 %"

Funciones de control de luz

El MCP ahora admite capacidades avanzadas de control de iluminación:

  1. Control de color : configure cualquier color RGB para luces compatibles

    • Especifique colores utilizando valores RGB (0-255 para cada componente)

    • Ejemplo: set_device_color("light.living_room", 255, 0, 0) para rojo

  2. Control de brillo : ajusta el brillo de la luz

    • 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 medio brillante

Solución de problemas

  • Si recibe errores de autenticación, verifique que su token sea correcto y no haya expirado

  • Verifique que su instancia de Home Assistant sea accesible en la URL configurada

  • Para problemas de control de color:

    • Verifique que su entidad de luz admita el control de color RGB

    • Compruebe que la luz esté encendida antes de intentar cambiar de color.

Capacidades futuras

Exposición de entidades dinámicas

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

  1. Búsqueda de entidades mediante lenguaje natural

  2. Controlar la entidad utilizando su entity_id específico

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

  • Controlar directamente los dispositivos a través de comandos más naturales (por ejemplo, "apagar las luces de la cocina")

  • Almacene en caché las entidades utilizadas frecuentemente para un acceso más rápido

  • Admite operaciones más complejas, como ajustar el brillo, la temperatura u otros atributos.

  • Manejar 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 Home Assistant a través de un asistente de IA.

Available Tools

3 tools
control_deviceB

Control a Home Assistant entity by turning it on or off.

Args:
    entity_id: The Home Assistant entity ID to control (format: domain.entity)
    state: The desired state ('on' or 'off')

Inputs: entity_id (required), state (required).

search_entitiesA

Search for Home Assistant entities matching a natural language description.

Args:
    description: Natural language description of the entity (e.g., "office light", "kitchen fan")

Returns:
    A list of matching entity IDs with their friendly names, or an error message

Inputs: description (required).

set_device_colorA

Set the color and optionally brightness of a light entity.

Args:
    entity_id: The Home Assistant entity ID to control (format: light.entity)
    red: Red component (0-255)
    green: Green component (0-255)
    blue: Blue component (0-255)
    brightness: Optional brightness level (0-255)

Inputs: entity_id (required), red (required), green (required), blue (required), +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap. control_device handles basic on/off states, search_entities finds devices by description, and set_device_color manages color/brightness for lights. An agent can easily distinguish when to use each tool based on the specific operation needed.

    Naming Consistency5/5

    All three tools follow a consistent verb_noun pattern with snake_case throughout: control_device, search_entities, and set_device_color. The naming is predictable and follows the same grammatical structure, making the tool set easy to understand at a glance.

    Tool Count3/5

    With only 3 tools, this feels thin for a Home Assistant integration that presumably manages many device types and operations. While the tools cover basic control, search, and color settings, the scope suggests more operations would be needed for comprehensive home automation coverage. The count is borderline minimal for the domain.

    Completeness2/5

    There are significant gaps in the tool surface for home automation. Missing operations include getting device status/state, adjusting non-color attributes (like temperature for thermostats or speed for fans), managing scenes/automations, and handling other entity types beyond lights. The current tools provide only partial coverage of the Home Assistant domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that integrates with Home Assistant to provide smart home control capabilities through natural language, supporting devices like lights, climate systems, locks, alarms, and humidifiers.
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.
      29
      353
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to control Home Assistant devices and services through the Model Context Protocol.
      106
      MIT