Servidor de protocolo de contexto de modelo para Home Assistant

El servidor utiliza el protocolo MCP para compartir el acceso a una instancia local de Home Assistant con una aplicación LLM.

Un potente puente entre su instancia de Home Assistant y los Modelos de Aprendizaje de Lenguaje (LLM), que permite el control y la monitorización del lenguaje natural de sus dispositivos domésticos inteligentes mediante el Protocolo de Contexto de Modelo (MCP). Este servidor proporciona una API integral para gestionar todo su ecosistema de Home Assistant, desde el control de dispositivos hasta la administración del sistema.

Características

🎮 Control de dispositivos : controla cualquier dispositivo Home Assistant mediante lenguaje natural
🔄 Actualizaciones en tiempo real : Obtenga actualizaciones instantáneas a través de eventos enviados por el servidor (SSE)
🤖 Gestión de automatización : crea, actualiza y gestiona automatizaciones
📊 Monitoreo de estado : rastrea y consulta los estados del dispositivo
🔐 Seguro : Autenticación basada en tokens y limitación de velocidad
Compatible con dispositivos móviles : funciona con cualquier cliente compatible con HTTP

Actualizaciones en tiempo real con SSE

El servidor incluye un potente sistema de Eventos Enviados por el Servidor (SSE) que proporciona actualizaciones en tiempo real desde su instancia de Home Assistant. Esto le permite:

🔄 Obtenga cambios de estado instantáneos para cualquier dispositivo
📡 Supervisar los desencadenadores y ejecuciones de automatización
🎯 Suscríbete a dominios o entidades específicas
📊 Realizar un seguimiento de las llamadas de servicio y las ejecuciones de scripts

Ejemplo rápido de SSE

const eventSource = new EventSource(
  'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update received:', data);
};

Consulte SSE_API.md para obtener la documentación completa del sistema SSE.

Tabla de contenido

Características principales
Prerrequisitos
Instalación
- Configuración básica
- Configuración de Docker (recomendada)
Configuración
Desarrollo
Referencia de API
Integración del lenguaje natural
Solución de problemas
Estado del proyecto
Contribuyendo
Recursos
Licencia

Características principales

Funcionalidad principal 🎮

Control de dispositivos inteligentes
- 💡 Luces : Brillo, temperatura de color, color RGB
- 🌡️ Clima : Temperatura, modos HVAC, modos de ventilador, humedad
- 🚪 Cubiertas : Control de posición e inclinación
- 🔌 Interruptores : Control de encendido/apagado
- 🚨 Sensores y contactos : Monitoreo de estado
- 🎵 Reproductores multimedia : Control de reproducción, volumen, selección de fuente
- 🌪️ Ventiladores : Velocidad, oscilación, dirección
- 🔒 Cerraduras : Control de bloqueo/desbloqueo
- 🧹 Aspiradoras : Arrancar, parar, volver a la base
- 📹 Cámaras : Detección de movimiento, instantáneas

Gestión del sistema 🛠️

Gestión de complementos
- Explorar los complementos disponibles
- Instalar/desinstalar complementos
- Iniciar/detener/reiniciar complementos
- Gestión de versiones
- Acceso a la configuración
Gestión de paquetes (HACS)
- Integración con la tienda comunitaria de Home Assistant
- Admite múltiples tipos de paquetes:
  - Integraciones personalizadas
  - Temas de interfaz
  - Scripts de Python
  - Aplicaciones AppDaemon
  - Aplicaciones NetDaemon
- Control de versiones y actualizaciones
- Gestión de repositorios
Gestión de la automatización
- Crear y editar automatizaciones
- Opciones de configuración avanzadas:
  - Múltiples tipos de disparadores
  - Condiciones complejas
  - Secuencias de acción
  - Modos de ejecución
- Duplicar y modificar automatizaciones existentes
- Habilitar o deshabilitar reglas de automatización
- Activar la automatización manualmente

Características de la arquitectura 🏗️

Organización inteligente
- Agrupación de dispositivos por área y piso
- Monitoreo y consulta del estado
- Conciencia del contexto inteligente
- Acceso a datos históricos
Arquitectura robusta
- Manejo integral de errores
- Validación estatal
- Integración segura de API
- Seguridad de tipos de TypeScript
- Amplia cobertura de pruebas

Prerrequisitos

Node.js 20.10.0 o superior
Gestor de paquetes NPM
Docker Compose para la contenedorización
Ejecución de la instancia de Home Assistant
Token de acceso de larga duración de Home Assistant ( Cómo obtener el token )
HACS instalado para funciones de gestión de paquetes
Acceso de supervisor para la gestión de complementos

Instalación

Instalación mediante herrería

Para instalar Home Assistant MCP Server para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install @drejom/homeassistant-mcp --client claude

Configuración básica

# Clone the repository
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuración de Docker (recomendada)

El proyecto incluye soporte para Docker para una fácil implementación y entornos consistentes en diferentes plataformas.

Clonar el repositorio:
git clone https://github.com/jango-blockchained/homeassistant-mcp.git cd homeassistant-mcp
Configurar el entorno:
cp .env.example .env
Edite el archivo .env con la configuración de Home Assistant:
# Home Assistant Configuration HASS_HOST=http://homeassistant.local:8123 HASS_TOKEN=your_home_assistant_token HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket # Server Configuration PORT=3000 NODE_ENV=production DEBUG=false
Construya y ejecute con Docker Compose:
# Build and start the containers docker compose up -d # View logs docker compose logs -f # Stop the service docker compose down
Verifique la instalación: El servidor debería estar ejecutándose en http://localhost:3000 . Puede verificar el estado del punto final en http://localhost:3000/health .
Actualizar la aplicación:
# Pull the latest changes git pull # Rebuild and restart the containers docker compose up -d --build

Configuración de Docker

La configuración de Docker incluye:

Construcción en varias etapas para un tamaño de imagen óptimo
Controles de salud para la monitorización de contenedores
Montaje de volumen para la configuración del entorno
Reinicio automático del contenedor en caso de fallo
Puerto 3000 expuesto para acceso a API

Variables de entorno de Docker Compose

Todas las variables de entorno se pueden configurar en el archivo .env . Se admiten las siguientes variables:

HASS_HOST : URL de su instancia de Home Assistant
HASS_TOKEN : Token de acceso de larga duración para Home Assistant
HASS_SOCKET_URL : URL de WebSocket para Home Assistant
PORT : Puerto del servidor (predeterminado: 3000)
NODE_ENV : Entorno (producción/desarrollo)
DEBUG : Habilitar el modo de depuración (verdadero/falso)

Configuración

Variables de entorno

# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123  # Your Home Assistant instance URL
HASS_TOKEN=your_home_assistant_token       # Long-lived access token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # WebSocket URL

# Server Configuration
PORT=3000                # Server port (default: 3000)
NODE_ENV=production     # Environment (production/development)
DEBUG=false            # Enable debug mode

# Test Configuration
TEST_HASS_HOST=http://localhost:8123  # Test instance URL
TEST_HASS_TOKEN=test_token           # Test token

Archivos de configuración

Desarrollo : Copiar .env.example a .env.development
Producción : Copiar .env.example a .env.production
Prueba : Copiar .env.example a .env.test

Agregar a Claude Desktop (u otros clientes)

Para usar su nuevo servidor MCP de Home Assistant, puede agregar Claude Desktop como cliente. Agregue lo siguiente a la configuración. Tenga en cuenta que esto ejecutará el MCP dentro de Claude y no funciona con el método Docker.

{
  "homeassistant": {
    "command": "node",
    "args": [<path/to/your/dist/folder>]
    "env": {
      NODE_ENV=development
      HASS_HOST=http://homeassistant.local:8123
      HASS_TOKEN=your_home_assistant_token
      PORT=3000
      HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
      LOG_LEVEL=debug
    }
  }
}

Referencia de API

Control de dispositivos

Controles de entidad comunes

{
  "tool": "control",
  "command": "turn_on",  // or "turn_off", "toggle"
  "entity_id": "light.living_room"
}

Control de luz

{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room",
  "brightness": 128,
  "color_temp": 4000,
  "rgb_color": [255, 0, 0]
}

Gestión de complementos

Lista de complementos disponibles

{
  "tool": "addon",
  "action": "list"
}

Instalar complemento

{
  "tool": "addon",
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}

Administrar el estado del complemento

{
  "tool": "addon",
  "action": "start",  // or "stop", "restart"
  "slug": "core_configurator"
}

Gestión de paquetes

Lista de paquetes HACS

{
  "tool": "package",
  "action": "list",
  "category": "integration"  // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}

Instalar paquete

{
  "tool": "package",
  "action": "install",
  "category": "integration",
  "repository": "hacs/integration",
  "version": "1.32.0"
}

Gestión de la automatización

Crear automatización

{
  "tool": "automation_config",
  "action": "create",
  "config": {
    "alias": "Motion Light",
    "description": "Turn on light when motion detected",
    "mode": "single",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "binary_sensor.motion",
        "to": "on"
      }
    ],
    "action": [
      {
        "service": "light.turn_on",
        "target": {
          "entity_id": "light.living_room"
        }
      }
    ]
  }
}

Automatización duplicada

{
  "tool": "automation_config",
  "action": "duplicate",
  "automation_id": "automation.motion_light"
}

Funciones principales

Gestión del Estado

GET /api/state
POST /api/state

Gestiona el estado actual del sistema.

Ejemplo de solicitud:

POST /api/state
{
  "context": "living_room",
  "state": {
    "lights": "on",
    "temperature": 22
  }
}

Actualizaciones de contexto

POST /api/context

Actualiza el contexto actual con nueva información.

Ejemplo de solicitud:

POST /api/context
{
  "user": "john",
  "location": "kitchen",
  "time": "morning",
  "activity": "cooking"
}

Puntos finales de acción

Ejecutar acción

POST /api/action

Ejecuta una acción especificada con los parámetros dados.

Ejemplo de solicitud:

POST /api/action
{
  "action": "turn_on_lights",
  "parameters": {
    "room": "living_room",
    "brightness": 80
  }
}

Acciones por lotes

POST /api/actions/batch

Ejecuta múltiples acciones en secuencia.

Ejemplo de solicitud:

POST /api/actions/batch
{
  "actions": [
    {
      "action": "turn_on_lights",
      "parameters": {
        "room": "living_room"
      }
    },
    {
      "action": "set_temperature",
      "parameters": {
        "temperature": 22
      }
    }
  ]
}

Funciones de consulta

Obtener acciones disponibles

GET /api/actions

Devuelve una lista de todas las acciones disponibles.

Ejemplo de respuesta:

{
  "actions": [
    {
      "name": "turn_on_lights",
      "parameters": ["room", "brightness"],
      "description": "Turns on lights in specified room"
    },
    {
      "name": "set_temperature",
      "parameters": ["temperature"],
      "description": "Sets temperature in current context"
    }
  ]
}

Consulta de contexto

GET /api/context?type=current

Recupera información de contexto.

Ejemplo de respuesta:

{
  "current_context": {
    "user": "john",
    "location": "kitchen",
    "time": "morning",
    "activity": "cooking"
  }
}

Eventos de WebSocket

El servidor admite actualizaciones en tiempo real a través de conexiones WebSocket.

// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};

Eventos apoyados

state_change : Se emite cuando cambia el estado del sistema
context_update : se emite cuando se actualiza el contexto
action_executed : Se emite cuando se completa una acción
error : se emite cuando ocurre un error

Ejemplo de datos de evento:

{
  "event": "state_change",
  "data": {
    "previous_state": {
      "lights": "off"
    },
    "current_state": {
      "lights": "on"
    },
    "timestamp": "2024-03-20T10:30:00Z"
  }
}

Manejo de errores

Todos los puntos finales devuelven códigos de estado HTTP estándar:

200: Éxito
400: Solicitud incorrecta
401: No autorizado
403: Prohibido
404: No encontrado
500: Error interno del servidor

Formato de respuesta de error:

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Missing required parameter: room",
    "details": {
      "missing_fields": ["room"]
    }
  }
}

Limitación de velocidad

La API implementa una limitación de velocidad para evitar abusos:

100 solicitudes por minuto por IP para puntos finales regulares
1000 solicitudes por minuto por IP para conexiones WebSocket

Cuando se excede el límite de velocidad, el servidor devuelve:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "reset_time": "2024-03-20T10:31:00Z"
  }
}

Ejemplo de uso

Usando curl

# Get current state
curl -X GET \
  http://localhost:3000/api/state \
  -H 'Authorization: ApiKey your_api_key_here'

# Execute action
curl -X POST \
  http://localhost:3000/api/action \
  -H 'Authorization: ApiKey your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "turn_on_lights",
    "parameters": {
      "room": "living_room",
      "brightness": 80
    }
  }'

Usando JavaScript

// Execute action
async function executeAction() {
  const response = await fetch('http://localhost:3000/api/action', {
    method: 'POST',
    headers: {
      'Authorization': 'ApiKey your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'turn_on_lights',
      parameters: {
        room: 'living_room',
        brightness: 80
      }
    })
  });
  
  const data = await response.json();
  console.log('Action result:', data);
}

Desarrollo

# Development mode with hot reload
npm run dev

# Build project
npm run build

# Production mode
npm run start

# Run tests
npx jest --config=jest.config.cjs

# Run tests with coverage
npx jest --coverage

# Lint code
npm run lint

# Format code
npm run format

Solución de problemas

Problemas comunes

Versión de Node.js ( toSorted is not a function )
- Solución: Actualizar a Node.js 20.10.0+ GXP39
Problemas de conexión
- Verificar que Home Assistant se esté ejecutando
- Comprobar la accesibilidad HASS_HOST
- Validar permisos de token
- Asegúrese de la conexión WebSocket para actualizaciones en tiempo real
Problemas de gestión de complementos
- Verificar el acceso del supervisor
- Comprobar la compatibilidad de los complementos
- Validar los recursos del sistema
Problemas de integración de HACS
- Verificar la instalación de HACS
- Comprobar el estado de la integración de HACS
- Validar el acceso al repositorio
Problemas de automatización
- Verificar la disponibilidad de la entidad
- Comprobar las condiciones de activación
- Validar llamadas de servicio
- Supervisar los registros de ejecución

Estado del proyecto

✅ Completo

Acceso a entidades, pisos y áreas
Control de dispositivos (luces, clima, cubiertas, interruptores, contactos)
Sistema de gestión de complementos
Gestión de paquetes a través de HACS
Configuración de automatización avanzada
Gestión básica del estado
Manejo de errores y validación
Contenedorización de Docker
Configuración de prueba de Jest
Integración con TypeScript
Gestión de variables ambientales
Integración de la API de Home Assistant
Documentación del proyecto

🚧 En progreso

Implementación de WebSocket para actualizaciones en tiempo real
Funciones de seguridad mejoradas
Optimización de la organización de herramientas
Optimización del rendimiento
Integración del contexto de recursos
Generación de documentación de API
Integración de escritorio multiplataforma
Recuperación avanzada de errores
Pruebas de indicaciones personalizadas
Integración mejorada con macOS
Mejoras en la seguridad de tipos
Ampliación de la cobertura de pruebas

Contribuyendo

Bifurcar el repositorio
Crear una rama de características
Implementa tus cambios
Agregar pruebas para nuevas funcionalidades
Asegúrese de que todas las pruebas pasen
Enviar una solicitud de extracción

Recursos

Licencia

Licencia MIT - Ver archivo LICENCIA

Integrations

Servidor de protocolo de contexto de modelo para Home Assistant

Características

Actualizaciones en tiempo real con SSE

Ejemplo rápido de SSE

Tabla de contenido

Características principales

Funcionalidad principal 🎮

Gestión del sistema 🛠️

Características de la arquitectura 🏗️

Prerrequisitos

Instalación

Instalación mediante herrería

Configuración básica

Configuración de Docker (recomendada)

Configuración de Docker

Variables de entorno de Docker Compose

Configuración

Variables de entorno

Archivos de configuración

Agregar a Claude Desktop (u otros clientes)

Referencia de API

Control de dispositivos

Controles de entidad comunes

Control de luz

Gestión de complementos

Lista de complementos disponibles

Instalar complemento

Administrar el estado del complemento

Gestión de paquetes

Lista de paquetes HACS

Instalar paquete

Gestión de la automatización

Crear automatización

Automatización duplicada

Funciones principales

Gestión del Estado

Actualizaciones de contexto

Puntos finales de acción

Ejecutar acción

Acciones por lotes

Funciones de consulta

Obtener acciones disponibles

Consulta de contexto

Eventos de WebSocket

Eventos apoyados

Manejo de errores

Limitación de velocidad

Ejemplo de uso

Usando curl

Usando JavaScript

Desarrollo

Solución de problemas

Problemas comunes

Estado del proyecto

Contribuyendo

Recursos

Licencia

Related Resources

Appeared in Searches