Servidor MCP de Home Assistant

Un servidor de Protocolo de Contexto de Modelo (MCP) para integrarse con Home Assistant , lo que permite a los LLM controlar y consultar su hogar inteligente.

Características

• Consultar y controlar entidades de Home Assistant mediante lenguaje natural

• Funciona con cualquier cliente compatible con MCP (como Claude Desktop)

• Proporciona herramientas para la gestión de estados, llamadas de servicio, historial y más.

• Autenticación segura mediante tokens de acceso de larga duración de Home Assistant

• Múltiples opciones de transporte (stdio para procesos locales, SSE para clientes remotos)

• Modo de demostración con datos simulados para realizar pruebas y demostraciones cuando Home Assistant no está disponible

Related MCP server: Home Assistant MCP Server

Instalación

# Install globally using bun
bun install -g home-assistant-mcp-server

# Or install from source
git clone https://github.com/oleander/home-assistant-mcp-server.git
cd home-assistant-mcp-server
bun install
bun run build
bun link

Configuración

Crea un archivo .env en tu directorio actual con las siguientes variables:

# Required configurations
HASS_URL=http://your-home-assistant:8123  # URL to your Home Assistant instance
HASS_TOKEN=your_long_lived_access_token   # Long-lived access token for authentication

# Optional configurations
PORT=3000                # Port for the HTTP server (default: 3000)
HASS_MOCK=false          # Enable mock data mode when Home Assistant is unavailable (default: false)

Variables de entorno

Para obtener un token de acceso de larga duración:

1. Inicie sesión en su instancia de Home Assistant

2. Haz clic en tu perfil (abajo a la izquierda)

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

4. Crea un nuevo token con un nombre descriptivo

5. Copia el valor del token (no lo volverás a ver)

Uso

Ejecutándose como un servidor independiente

# Standard mode (requires a running Home Assistant instance)
home-assistant-mcp-server                # Start with HTTP/SSE transport
home-assistant-mcp-server --stdio        # Start with stdio transport for direct process communication

# Demo mode (with mock data when Home Assistant is unavailable)
home-assistant-mcp-server --mock         # Start with HTTP/SSE transport and mock data
home-assistant-mcp-server --stdio --mock # Start with stdio transport and mock data

Integración con Claude Desktop

Para utilizar con Claude Desktop:

1. Edite el archivo de configuración de Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Ventanas: %APPDATA%\Claude\claude_desktop_config.json

2. Agregue la configuración del servidor:

{
  "mcpServers": {
    "homeassistant": {
      "command": "home-assistant-mcp-server"
      "env": {
        "HASS_URL": "http://your-home-assistant:8123",
        "HASS_TOKEN": "your_token_here",
        "HASS_MOCK": "true"
      }
    }
  }
}

Si tiene Home Assistant ejecutándose, simplemente elimine el indicador --mock y configure HASS_MOCK en false .

3. Reiniciar Claude Desktop

Herramientas disponibles

El servidor expone varias herramientas para interactuar con Home Assistant:

• states - Consultar estados de entidad

• lights - Lista de luces

• light - Controlar una luz

• service - Servicios de Call Home Assistant

• history - Recuperar datos históricos de entidades

• services - Lista de servicios disponibles

• config - Obtener la configuración de Home Assistant

• domains - Lista de dominios disponibles

• error_log - Obtener el registro de errores de Home Assistant

• devices : Obtener todos los dispositivos en Home Assistant

Para obtener ejemplos de uso detallados, consulte docs/hass-mcp.md .

Seguridad

Este servidor requiere un token de acceso de Home Assistant con acceso completo. Tenga en cuenta estas recomendaciones de seguridad:

• Ejecute el servidor únicamente en redes confiables

• Utilice HTTPS si expone el servidor de forma remota

• Mantenga su archivo .env seguro y no lo envíe al control de código fuente

• Considere usar un token con permisos limitados cuando sea posible

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.