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

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

Variable	Requerido	Por defecto	Descripción
`HASS_URL`	Sí	-	URL a su instancia de Home Assistant (por ejemplo, http://homeassistant.local:8123 )
`HASS_TOKEN`	Sí	-	Token de acceso de larga duración para la autenticación con Home Assistant
`PORT`	No	3000	Número de puerto para el servidor HTTP cuando se utiliza el transporte HTTP/SSE
`HASS_MOCK`	No	FALSO	Cuando se establece en "verdadero", habilita el modo de datos simulados para realizar pruebas sin una conexión a Home Assistant.

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

Inicie sesión en su instancia de Home Assistant
Haz clic en tu perfil (abajo a la izquierda)
Desplácese hacia abajo hasta "Tokens de acceso de larga duración".
Crea un nuevo token con un nombre descriptivo
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:

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

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.

Home Assistant MCP Server

Integrations