MCP-HA-Connect

Un servidor del Protocolo de Contexto de Modelo (MCP) listo para producción para la integración de Home Assistant con asistentes de IA como Claude.

GitHub

Documentación

MCP-HA-Connect

Un servidor de Model Context Protocol (MCP) listo para producción para la integración de Home Assistant con asistentes de IA como Claude y LM Studio.

Consulta docs/QUICK_START.md para Docker, modo servidor HTTP, integración con n8n y más opciones de instalación.

Características Principales

Funcionalidad Principal

Control Inteligente de Dispositivos
Luces: Brillo, temperatura de color, color RGB, transiciones
Clima: Temperatura, modos HVAC, modos de ventilador, humedad
Coberturas: 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: Iniciar, detener, regresar a la base
Cámaras: Detección de movimiento, capturas

Gestión de Automatizaciones

Listar todas las automatizaciones con estado
Activar automatizaciones manualmente con variables
Habilitar/deshabilitar/alternar automatizaciones
Crear nuevas automatizaciones mediante API
Eliminar automatizaciones
Ver trazas de ejecución de automatizaciones
Recargar automatizaciones desde la configuración

Características del Sistema

Integración directa con la API de Home Assistant
Autenticación con token de acceso de larga duración
Gestión de estados de entidades
Soporte de llamadas a servicios
Búsqueda avanzada de entidades
Análisis de sensores impulsado por IA con Ollama
Múltiples modos de transporte (stdio, HTTP Streamable)
Servidor HTTP con comprobaciones de salud
Soporte CORS para clientes basados en navegador
Registro estructurado (formatos plano, JSON, GCP-JSON)
Validación integral de configuración con Zod
Seguridad total de tipos con TypeScript
Soporte de sesiones con y sin estado
Autenticación JWT con control de acceso basado en roles
Instrucciones del servidor MCP para una mejor selección de herramientas LLM

Monitoreo de Red y Seguridad (TP-Link Omada)

Lleva tu red doméstica al mismo asistente que gestiona tu hogar. Estas son las preguntas de alto valor que un LLM puede responder realmente sobre tu red:

Estado de Internet y WAN — "¿Está mi internet activo? ¿Cuál es mi IP WAN y velocidad de enlace?" Estado en vivo por WAN, además de salud multi-WAN / ISP y balanceo de carga para la puerta de enlace.
Registros de eventos y alertas — "¿Qué pasó en mi red?" Los registros de eventos y alertas del sitio, con ventana de tiempo (por defecto los últimos 7 días), para correlacionar con el historial de Home Assistant.
Seguridad inalámbrica — Resultados de escaneo de AP rogue y (en Omada Pro) detección de intrusiones inalámbricas (WIDS) para una conciencia genuina de seguridad de red.
Salud del controlador y dispositivos — Resumen del panel más los principales dispositivos por uso de CPU y memoria, monitoreo estilo HA de tu pila de red.
Pruebas de velocidad — Superficie los resultados de pruebas de velocidad del propio controlador, combinando con analyzeSensors impulsado por IA para detección de anomalías.
Dispositivos pendientes — "¿Hay un nuevo dispositivo esperando ser adoptado?"
Conciencia de firmware — Información de firmware por dispositivo y una visión general de actualizaciones críticas a nivel de controlador, reflejando la filosofía de checkUpdates de Home Assistant en toda la red.
Gestión de clientes — Listar/inspeccionar clientes conectados, actividad de tráfico y aplicar perfiles de límite de velocidad, con correlación de presencia contra los rastreadores de dispositivos de Home Assistant.

Un modo de grafo de recursos descubrible (MCP_TOOL_REGISTRATION_MODE=graph) expone todo lo anterior a través de dos herramientas — omada_browse + omada_read — manteniendo el presupuesto de esquema de herramientas pequeño para modelos de bajo contexto. Consulta las tablas de herramientas de Omada a continuación para la superficie completa.

Herramientas Disponibles (69 en Total)

Herramientas de Home Assistant (38)

Herramientas de Estado y Entidades

Herramienta	Descripción
`getStates`	Obtener todos los estados de entidades (paginado, 50/página por defecto). Usa `includeAttributes=true` para datos completos
`getState`	Obtener el estado de una entidad específica por entity_id
`getEntitiesByDomain`	Obtener entidades para un dominio (paginado, 50/página por defecto). Usa `includeAttributes=true` para datos completos
`searchEntities`	Buscar entidades por nombre/entity_id (paginado, 50/página por defecto). Usa `includeAttributes=true` para datos completos
`getAllSensors`	Obtener todos los sensores (paginado, 50/página por defecto). Usa `includeAttributes=true` para datos completos
`listEntities`	Listar entidades con filtrado (dominio, estado, búsqueda, límite). Usa `includeAttributes=true` para datos completos
`getDomainSummary`	Obtener estadísticas resumidas para un dominio
`getHistory`	Obtener datos históricos para una entidad
`listPersons`	Listar todos los miembros del hogar con estado de ubicación (en casa/fuera)

Herramientas de Servicio y Control

Herramienta	Descripción
`callService`	Llamar a cualquier servicio de Home Assistant
`entityAction`	Acciones simples de encender/apagar/alternar

Herramientas de Control de Dispositivos

Herramienta	Descripción
`controlLight`	Controlar luces con brillo, color, temperatura
`controlClimate`	Controlar termostatos con temperatura, modo HVAC
`controlMediaPlayer`	Controlar reproductores multimedia con reproducción, volumen
`controlCover`	Controlar coberturas/persianas con posición, inclinación
`controlFan`	Controlar ventiladores con velocidad, oscilación, dirección
`activateScene`	Activar una escena de Home Assistant
`runScript`	Ejecutar un script de Home Assistant
`sendNotification`	Enviar notificaciones con soporte completo de aplicación móvil (acciones, prioridad, imágenes)
`listNotificationTargets`	Descubrir objetivos de notificación disponibles de la aplicación móvil

Preguntas al Propietario (aprobación en el teléfono)

Haz una pregunta al propietario como notificación de teléfono con hasta 3 botones y lee la respuesta. Solo modo HTTP; necesita un token de Home Assistant de administrador (los toques de botón son eventos solo de administrador) y MCP_AUTH_SECRET para que las preguntas abiertas sobrevivan a un reinicio. Todo excepto una respuesta de aprobación explícita cuenta como NO.

Herramienta	Descripción
`askOwner`	Enviar la pregunta (texto plano, máximo 256 caracteres; 1-3 botones, por defecto Aprobar / Rechazar; abierta hasta 7 días) y devolver un `requestId` de inmediato
`getOwnerAnswer`	Esperar hasta 50 s por llamada: `answered` (índice y etiqueta del botón, hora, usuario de HA), `pending`, `timeout`, `cancelled` o `unknown`
`cancelOwnerQuestion`	Retirar una pregunta abierta; la notificación cambia a "Cancelada"

Los toques se verifican con identificadores de botón firmados y deben provenir de la aplicación móvil (una automatización no puede falsificarlos); establece MCP_OWNER_QUESTIONS_HA_USERS para que solo tu usuario de HA pueda responder. Solo el cliente que preguntó puede leer la respuesta; como máximo 3 preguntas abiertas y 30 por hora por cliente.

Límite conocido: las cancelaciones y respuestas se mantienen en memoria. Después de un reinicio, alguien con un inicio de sesión de Home Assistant podría reenviar un identificador de botón antiguo a través de la propia API de HA y responder una pregunta que había sido cancelada o rechazada (el teléfono ya no muestra sus botones). Ese acceso ya permite controlar la casa directamente.

Herramientas de Automatización

Herramienta	Descripción
`listAutomations`	Listar todas las automatizaciones con estado
`triggerAutomation`	Activar manualmente una automatización
`enableAutomation`	Habilitar una automatización deshabilitada
`disableAutomation`	Deshabilitar una automatización
`toggleAutomation`	Alternar el estado de una automatización
`reloadAutomations`	Recargar automatizaciones desde la configuración
`createAutomation`	Crear una nueva automatización
`deleteAutomation`	Eliminar una automatización
`getAutomationTrace`	Ejecuciones recientes de una automatización, más recientes primero: disparador, resultado, errores (solo automatizaciones con un `id`)

Herramientas del Sistema

Herramienta	Descripción
`getVersion`	Obtener la versión de Home Assistant e información de configuración
`restartHomeAssistant`	Reiniciar el servidor de Home Assistant
`getSystemLog`	Obtener entradas de registro del sistema desde el libro de registro
`checkUpdates`	Verificar actualizaciones disponibles

Herramientas de Calendario

Herramienta	Descripción
`listCalendars`	Listar todas las entidades de calendario
`getCalendarEvents`	Obtener eventos de uno o todos los calendarios

Herramientas de Red Omada (49)

Herramientas de Sitio

Herramienta	Descripción
`omada_listSites`	Listar todos los sitios configurados en el controlador Omada

Herramientas de Dispositivos

Herramienta	Descripción
`omada_listDevices`	Listar todos los dispositivos de red (APs, switches, puertas de enlace) en un sitio
`omada_getDevice`	Obtener información detallada sobre un dispositivo de red específico
`omada_searchDevices`	Buscar dispositivos globalmente en todos los sitios
`omada_getSwitchStackDetail`	Obtener información detallada sobre una pila de switches
`omada_listDevicesStats`	Obtener estadísticas para dispositivos adoptados globales con filtrado

Herramientas de Clientes

Herramienta	Descripción
`omada_listClients`	Listar todos los clientes conectados (dispositivos/usuarios) en un sitio
`omada_getClient`	Obtener información detallada sobre un cliente conectado específico
`omada_listMostActiveClients`	Obtener los clientes más activos ordenados por tráfico total
`omada_listClientsActivity`	Obtener estadísticas de actividad de clientes a lo largo del tiempo
`omada_listClientsPastConnections`	Obtener datos históricos de conexión de clientes

Herramientas de Límite de Velocidad

Herramienta	Descripción
`omada_getRateLimitProfiles`	Obtener perfiles de límite de velocidad disponibles para un sitio
`omada_setClientRateLimit`	Establecer límites de ancho de banda personalizados para un cliente (descarga/subida en Kbps)
`omada_setClientRateLimitProfile`	Aplicar un perfil de límite de velocidad a un cliente
`omada_disableClientRateLimit`	Eliminar límites de ancho de banda de un cliente

Acciones de Clientes y Dispositivos

Herramienta	Descripción
`omada_blockClient`	Bloquear un cliente de la red
`omada_unblockClient`	Desbloquear un cliente previamente bloqueado (explica cuándo la API de Omada ya no puede alcanzar a un cliente sin conexión)
`omada_listBlockedClients`	Listar clientes bloqueados, incluidos los sin conexión
`omada_deleteClient`	Eliminar el registro de un cliente (nombre, historial, bloqueo) para limpiar un bloqueo que el desbloqueo no puede alcanzar (necesita `CONFIGURE`)
`omada_cyclePoePort`	Ciclo de energía en puertos PoE de switches (reinicio remoto de APs/cámaras)
`omada_setSsidEnabled`	Activar o desactivar un SSID (por ejemplo, WiFi de invitados) por nombre

Diagnóstico de Clientes y Grupos MAC

Herramienta	Descripción
`omada_diagnoseClient`	Explicar por qué un dispositivo (por MAC) no puede conectarse: estado de bloqueo, grupos MAC y las listas de permitir/denegar SSID que los usan, filtro MAC del sitio, enlace IP-MAC, reserva DHCP, y para llamadores ADMIN el registro de auditoría (detecta un bloqueo huérfano). Solo lectura
`omada_listMacGroups`	Listar grupos MAC con sus entradas y qué SSIDs los usan como listas de permitir o denegar (modo grafo: `omada_read /profiles/mac-groups`)
`omada_setMacGroupEntry`	Agregar una MAC a un grupo MAC, o renombrar su entrada (necesita `CONFIGURE`)
`omada_removeMacGroupEntry`	Eliminar una MAC de un grupo MAC (necesita `CONFIGURE`)

Control de Acceso (horarios, grupos, ACL de puerta de enlace)

Permite que el controlador aplique un horario por sí mismo (por ejemplo, un toque de queda) en lugar de un bucle diario de bloqueo/desbloqueo. Todas las escrituras necesitan CONFIGURE.

Herramienta	Descripción
`omada_listAccessControl`	Rangos de tiempo (ventanas legibles), grupos IP y reglas ACL de puerta de enlace con nombres y horarios (modo grafo: `omada_read` `/profiles/time-range`, `/profiles/ip-groups`, `/network/acls/gateway`)
`omada_createTimeRange` / `omada_updateTimeRange` / `omada_deleteTimeRange`	Horarios semanales en cuartos de hora, por ejemplo `{days:["mon","tue"], start:"14:30", end:"19:00"}`; `invertWindows` convierte las horas permitidas en las bloqueadas. Máximo 7 ventanas por perfil (un toque de queda necesita un perfil de mañana y uno de tarde). Se rechaza la eliminación mientras una regla lo use
`omada_createGroup` / `omada_deleteGroup`	Grupos IP (fuentes/destinos ACL) y grupos MAC (listas de permitir/denegar SSID); se rechaza la eliminación para grupos integrados y grupos en uso
`omada_setDhcpReservation` / `omada_removeDhcpReservation`	IP fija para un dispositivo (para que una ACL pueda coincidir); rechaza una dirección reservada para otro dispositivo
`omada_createGatewayAcl` / `omada_updateGatewayAcl` / `omada_deleteGatewayAcl` / `omada_moveGatewayAcl`	Reglas de puerta de enlace (router) LAN a internet: permitir/denegar una fuente (grupo IP, red LAN o SSID), opcionalmente solo durante un rango de tiempo; cubre cableado y Wi-Fi
`omada_setSsidMacFilter`	Activar el filtro MAC de un SSID (grupo MAC como lista de permitir o denegar) o desactivarlo; informa y rechaza desconectar clientes conectados a menos que `allowLockout`; `dryRun` previsualiza

Herramientas de Seguridad

Herramienta	Descripción
`omada_getThreatList`	Obtener lista de gestión de amenazas de seguridad

Herramientas de Configuración de Red

Herramienta	Descripción
`omada_getInternetInfo`	Obtener configuración de conexión a internet para un sitio
`omada_getPortForwardingStatus`	Obtener reglas de reenvío de puertos (Usuario o UPnP)
`omada_getLanNetworkList`	Obtener lista de configuración de red LAN
`omada_getLanProfileList`	Obtener lista de configuración de perfiles LAN
`omada_getWlanGroupList`	Obtener lista de configuración de grupos WLAN
`omada_getSsidList`	Obtener lista de SSID para un grupo WLAN
`omada_getSsidDetail`	Obtener configuración detallada de SSID
`omada_getFirewallSetting`	Obtener configuración de firewall para un sitio
`omada_getSiteNtpStatus`	Obtener configuración y estado del servidor NTP del sitio
`omada_setSiteNtpServers`	Reemplazar la lista de servidores NTP del sitio (necesita `CONFIGURE`; `dryRun` previsualiza el cambio)

Herramientas de Red Independientes del Proveedor (9)

Las herramientas net_ describen redes de la misma manera para cada proveedor de controladores: un modelo compartido, con un adaptador por proveedor (TP-Link Omada hoy; UniFi y MikroTik están planificados). Cada adaptador indica por característica si es nativa, construida a partir de varios objetos, o no soportada (net_capabilities), y rechaza lo que no puede hacer en lugar de omitirlo. Cada cambio se planifica primero: dryRun muestra los pasos, qué significan y qué dispositivos en línea se desconectarían; la aplicación rechaza si el controlador cambió mientras tanto, o si los dispositivos se desconectarían sin allowLockout. Las contraseñas de Wi-Fi nunca se toman ni se muestran: una red Wi-Fi nueva o restablecida obtiene una contraseña temporal aleatoria, y la real se establece en la interfaz web del controlador. Las lecturas necesitan QUERY, los cambios CONFIGURE.

Herramienta	Descripción
`net_capabilities`	Qué puede hacer el controlador, por característica
`net_listNetworks`	Redes (VLANs): VLAN, puerta de enlace, DHCP, IPv6, protegida
`net_createNetwork` / `net_updateNetwork` / `net_deleteNetwork`	Crear o cambiar una VLAN con su puerta de enlace y rango DHCP. La red en la que está el controlador está protegida; se rechaza la eliminación mientras una red Wi-Fi, perfil de puerto, reserva o regla la use
`net_listWifi`	Redes Wi-Fi: red, bandas, seguridad, aislamiento, filtro MAC
`net_createWifi` / `net_updateWifi` / `net_deleteWifi`	Crear o cambiar un SSID en una red determinada (bandas, WPA2/WPA3, PMF, aislamiento, oculto, 802.11r, filtro MAC), o restablecer su contraseña a una aleatoria

En Omada, el aislamiento de red, un tipo de red "invitado", activar IPv6 y el modo mixto WPA2/WPA3 no están disponibles a través de la API y se rechazan. Las reglas llegan en 2.4.6, los puertos de switch y mDNS en 2.4.7.

Herramientas de IA (1)

Herramienta	Descripción
`analyzeSensors`	Analizar datos de sensores usando IA (Ollama) para detectar problemas y proporcionar recomendaciones

Recursos MCP

URI del Recurso	Descripción
`hass://entities`	Listar todas las entidades agrupadas por dominio
`hass://entities/{entity_id}`	Obtener estado de una entidad específica
`hass://entities/{entity_id}/detailed`	Obtener información detallada de la entidad con todos los atributos
`hass://entities/domain/{domain}`	Obtener todas las entidades para un dominio
`hass://search/{query}/{limit}`	Buscar entidades con límite de resultados

Requisitos Previos

Node.js 20+ (probado con v20.19.6) - para métodos npm/npx
npm 10.8+ (probado con v10.8.2) - para métodos npm/npx
Docker (opcional) - para el método Docker
Instancia de Home Assistant con token de acceso de larga duración
Acceso de red a su instancia de Home Assistant
(Opcional) Ollama para análisis impulsado por IA

Cómo Obtener su Token de Home Assistant

Inicie sesión en su instancia de Home Assistant
Haga clic en su perfil (abajo a la izquierda)
Desplácese hacia abajo hasta "Tokens de Acceso de Larga Duración"
Haga clic en "Crear Token"
Asígnele un nombre (por ejemplo, "Servidor MCP")
Copie el token (¡se muestra solo una vez!)

Variables de Entorno

Requeridas

Variable	Descripción	Ejemplo
`HA_URL`	URL de Home Assistant	`http://homeassistant.10.0.0.19.nip.io:8123`
`HA_TOKEN`	Token de acceso de larga duración	`eyJhbGciOiJIUzI1NiIsInR5cCI...`

Opcionales - Home Assistant

Variable	Predeterminado	Descripción
`HA_PLUGIN_ENABLED`	`true`	Habilitar complemento de Home Assistant
`HA_STRICT_SSL`	`true`	Validar certificados SSL
`HA_TIMEOUT`	`30000`	Tiempo de espera de solicitud de API (ms)

Opcionales - Servidor MCP

Variable	Predeterminado	Descripción
`MCP_SERVER_LOG_LEVEL`	`info`	Nivel de registro: `debug`, `info`, `warn`, `error`
`MCP_SERVER_LOG_FORMAT`	`plain`	Formato de registro: `plain`, `json`, `gcp-json`
`MCP_SERVER_USE_HTTP`	`false`	Habilitar modo HTTP (en lugar de stdio)
`MCP_SERVER_STATEFUL`	`false`	Habilitar sesiones con estado en modo HTTP

Opcionales - Modo HTTP

Variable	Predeterminado	Descripción
`MCP_HTTP_PORT`	`3000`	Puerto del servidor HTTP
`MCP_HTTP_BIND_ADDR`	`127.0.0.1`	Dirección de enlace
`MCP_HTTP_PATH`	`/mcp`	Ruta del punto final MCP
`MCP_HTTP_ENABLE_HEALTHCHECK`	`true`	Habilitar punto final de verificación de salud
`MCP_HTTP_HEALTHCHECK_PATH`	`/health`	Ruta de verificación de salud
`MCP_HTTP_ALLOW_CORS`	`true`	Habilitar CORS
`MCP_HTTP_ALLOWED_ORIGINS`	`127.0.0.1,localhost`	Orígenes CORS permitidos

Opcionales - Interfaz de chat (superficie OpenAPI/REST)

El servidor también sirve una interfaz OpenAPI/REST (/openapi.json + /api/*) para interfaces de chat como Open WebUI. Por defecto expone las 8 herramientas clásicas de Home Assistant. Las herramientas marcadas como elegibles para chat en el código se pueden activar por categoría con granularidad de lectura/escritura:

Variable	Predeterminado	Descripción
`MCP_CHAT_TOOLS`	sin establecer (= 8 herramientas HA heredadas)	Porción de categoría, p. ej. `ha-core:rw,ha-history:r,omada-read:r`. Categorías: `ha-core`, `ha-history`, `ha-automations`, `omada-read`, `omada-write`. La configuración solo puede reducir lo que el código marca como elegible para chat; las herramientas ADMIN (`invokeAction`) nunca pueden aparecer en esta interfaz.
`MCP_REST_ACTIONS`	sin establecer (= herramienta no registrada)	Mapa JSON de acciones REST pre-registradas para la herramienta MCP `invokeAction` (ADMIN; solo interfaz MCP), p. ej. `{"deploy":{"url":"http://host:8425/v1/update","bearerToken":"...","cooldownMs":300000}}`. Cada acción tiene límite de velocidad: intervalo mínimo entre ejecuciones = `cooldownMs` (predeterminado 60000; `0` deshabilita) — limita el radio de explosión de implementación de tormenta si un modelo repite una acción legítima

Las herramientas de chat activadas aparecen en el /openapi.json generado como POST /api/tools/<name> y se envían a través de los mismos manejadores, validación y RBAC que la interfaz MCP.

Opcionales - Eventos SSE

Variable	Predeterminado	Descripción
`MCP_SSE_EVENTS_ENABLED`	`true`	Habilitar eventos SSE en tiempo real
`MCP_OWNER_QUESTIONS_ENABLED`	`true`	Habilitar `askOwner` / `getOwnerAnswer` / `cancelOwnerQuestion` (modo HTTP con Home Assistant)
`MCP_OWNER_QUESTIONS_HA_USERS`	(cualquier usuario de HA)	IDs de usuario de Home Assistant separados por comas permitidos para responder preguntas del propietario (el valor `answeredBy` de una respuesta)
`MCP_SSE_EVENTS_PATH`	`/subscribe_events`	Ruta del punto final SSE

Opcionales - Límite de Velocidad

Variable	Predeterminado	Descripción
`MCP_RATE_LIMIT_ENABLED`	`false`	Habilitar límite de velocidad
`MCP_RATE_LIMIT_WINDOW_MS`	`60000`	Ventana de límite de velocidad (ms)
`MCP_RATE_LIMIT_MAX_REQUESTS`	`100`	Máximo de solicitudes por ventana

Opcionales - Autenticación

Variable	Predeterminado	Descripción
`MCP_AUTH_METHOD`	`none`	Método de autenticación: `none` o `bearer`
`MCP_AUTH_SECRET`	-	Secreto de firma JWT (mínimo 32 caracteres, requerido para el método `bearer`)
`MCP_PERMISSIONS_CONFIG`	-	Configuración JSON para roles y permisos de usuario

Autenticación JWT

Cuando MCP_AUTH_METHOD=bearer, los clientes deben proporcionar un token JWT en el encabezado de Autorización:

Authorization: Bearer <jwt-token>

Genere tokens con su MCP_AUTH_SECRET usando el algoritmo HS256. La carga útil del JWT debe incluir:

sub (sujeto): Identificador de usuario para la búsqueda de permisos
exp (opcional): Marca de tiempo de expiración

Sistema de Permisos

El servidor utiliza control de acceso basado en roles con máscaras de permisos binarias:

Permiso	Bandera	Descripción
`ADMIN`	1	Operaciones del sistema (reinicio, actualizaciones)
`CONFIGURE`	2	Crear/modificar automatizaciones, scripts
`CONTROL`	4	Controlar dispositivos (luces, clima, etc.)
`QUERY`	8	Leer estados de entidades, historial, listas
`NOTIFY`	16	Enviar notificaciones
`AI`	32	Usar funciones de análisis de IA

Roles Predefinidos:

Rol	Permisos
`NONE`	Sin permisos
`READONLY`	Solo QUERY
`OPERATOR`	QUERY + CONTROL + NOTIFY
`CONTRIBUTOR`	QUERY + CONTROL + NOTIFY + CONFIGURE
`ADMIN`	Los seis permisos (QUERY, CONTROL, NOTIFY, CONFIGURE, AI, ADMIN)
`SUPERUSER`	Todos los permisos

Ejemplo de Configuración:

{
  "users": [
    { "sub": "admin@example.com", "role": "admin" },
    { "sub": "user@example.com", "role": "operator" },
    { "sub": "viewer@example.com", "role": "readonly" }
  ],
  "defaultRole": "NONE"
}

Establecer mediante variable de entorno (escape de comillas para shell):

MCP_PERMISSIONS_CONFIG='{"users":[{"sub":"admin","role":"admin"}],"defaultRole":"NONE"}'

Recomendado: defaultRole: "NONE" más una entrada users por cliente. defaultRole se aplica a cada token firmado válidamente cuyo sub no esté listado — un valor predeterminado no-NONE otorga silenciosamente acceso real a clientes no mapeados. El servidor registra una advertencia al inicio cuando defaultRole otorga algo. Mapee cada cliente (Open WebUI, n8n, agentes…) explícitamente antes de cambiar una implementación existente a NONE.

Los clientes solo ven las herramientas que pueden usar: tools/list se filtra por los permisos del llamador, por lo que un token readonly nunca recibe herramientas de control o administración (las llamadas aún se verifican por herramienta).

Opcionales - Proveedor de IA

Variable	Predeterminado	Descripción
`AI_PLUGIN_ENABLED`	`true`	Habilitar complemento de IA
`AI_PROVIDER`	`ollama`	Proveedor de IA: `ollama`, `openai`, o `none`
`AI_URL`	`http://localhost:11434`	URL del servidor de IA (Ollama)
`AI_MODEL`	`llama2`	Nombre del modelo de IA
`AI_TIMEOUT`	`60000`	Tiempo de espera de solicitud de IA (ms)

Opcionales - Controlador de Red Omada

Variable	Predeterminado	Descripción
`OMADA_PLUGIN_ENABLED`	`false`	Habilitar complemento Omada
`OMADA_BASE_URL`	-	URL del controlador Omada (p. ej., `https://10.0.0.1:8043`)
`OMADA_CLIENT_ID`	-	ID de cliente OAuth2 del controlador Omada
`OMADA_CLIENT_SECRET`	-	Secreto de cliente OAuth2 del controlador Omada
`OMADA_OMADAC_ID`	-	ID del controlador Omada
`OMADA_SITE_ID`	-	ID de sitio predeterminado para operaciones
`OMADA_STRICT_SSL`	`true`	Validar certificados SSL
`OMADA_TIMEOUT`	`30000`	Tiempo de espera de solicitud de API (ms)

Ejemplos Avanzados de Configuración

Con Análisis de IA (Ollama)

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["-y", "@coffeerunhobby/mcp-ha-connect"],
      "env": {
        "HA_URL": "http://homeassistant.10.0.0.19.nip.io:8123",
        "HA_TOKEN": "your_token",
        "AI_PROVIDER": "ollama",
        "AI_URL": "http://ollama.10.0.0.17.nip.io:11434",
        "AI_MODEL": "llama2"
      }
    }
  }
}

Deshabilitar Funciones de IA

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["-y", "@coffeerunhobby/mcp-ha-connect"],
      "env": {
        "HA_URL": "http://homeassistant.10.0.0.19.nip.io:8123",
        "HA_TOKEN": "your_token",
        "AI_PROVIDER": "none"
      }
    }
  }
}

Docker con Configuración de Red

Para Linux, es posible que necesite agregar host.docker.internal:

{
  "mcpServers": {
    "homeassistant": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--add-host=host.docker.internal:host-gateway",
        "-e", "HA_URL=http://host.docker.internal:8123",
        "-e", "HA_TOKEN=your_token",
        "ghcr.io/coffeerunhobby/mcp-ha-connect:latest"
      ]
    }
  }
}

Modos de Uso

Modo 1: Cliente MCP (Claude Desktop / LM Studio)

Modo stdio predeterminado para clientes MCP. Consulte la sección Inicio Rápido para la configuración.

Para opciones de configuración detalladas, consulte docs/LOCAL_CLIENT.md.

Modo 2: Servidor HTTP

Inicie como servidor HTTP independiente para aplicaciones web:

# Using npx
npx @coffeerunhobby/mcp-ha-connect

# Or with environment variables
MCP_SERVER_USE_HTTP=true \
MCP_HTTP_PORT=3000 \
HA_URL=http://homeassistant.10.0.0.19.nip.io:8123 \
HA_TOKEN=your_token \
npx @coffeerunhobby/mcp-ha-connect

Transporte HTTP Transmisible

Configure su cliente MCP para usar:

URL: http://localhost:3000/mcp
Transporte: HTTP Transmisible (MCP 2025-03-26)

Suscripción a Eventos SSE

Suscríbase a eventos en tiempo real:

const eventSource = new EventSource(
  'http://localhost:3000/subscribe_events?domain=light&entity_id=light.living_room'
);

eventSource.addEventListener('state_changed', (event) => {
  const data = JSON.parse(event.data);
  console.log('Entity changed:', data.entity_id, data.new_state);
});

Consulte docs/SSE_API.md para la documentación completa de SSE.

Modo 3: Docker Independiente

# Pull image
docker pull ghcr.io/coffeerunhobby/mcp-ha-connect:latest

# Run in HTTP mode
docker run -d --name mcp-ha-connect \
  -e HA_URL=http://homeassistant.10.0.0.19.nip.io:8123 \
  -e HA_TOKEN=your_token \
  -e MCP_SERVER_USE_HTTP=true \
  -p 3000:3000 \
  ghcr.io/coffeerunhobby/mcp-ha-connect:latest

Modo 4: Docker Compose

version: '3.8'

services:
  mcp-ha-connect:
    image: ghcr.io/coffeerunhobby/mcp-ha-connect:latest
    container_name: mcp-ha-connect
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - HA_URL=http://homeassistant.10.0.0.19.nip.io:8123
      - HA_TOKEN=${HA_TOKEN}
      - MCP_SERVER_USE_HTTP=true
      - MCP_HTTP_BIND_ADDR=0.0.0.0
    networks:
      - home-automation

networks:
  home-automation:
    driver: bridge

Ejemplos de Integración

Con Claude Desktop

Una vez configurado, puedes preguntarle a Claude:

"Muéstrame todas las luces de mi casa"
"Enciende las luces de la cocina al 50% de brillo"
"Establece la temperatura de la sala de estar a 72 grados"
"Crea una automatización que apague todas las luces a medianoche"
"¿Qué automatizaciones están habilitadas actualmente?"
"Activa la automatización de la rutina matutina"
"Busca entidades con 'dormitorio' en su nombre"
"Obtén todas las entidades de clima"
"Analiza mis sensores para detectar problemas" (requiere Ollama)
"Revisa el historial de mi termostato"

Con Flujos de Trabajo n8n

El servidor se puede integrar con n8n para monitoreo automatizado del hogar. Hay flujos de trabajo preconstruidos disponibles en el directorio n8n/:

ai-agent-safety-monitor - Monitoreo de seguridad crítico cada 5 minutos

Importación de Flujos de Trabajo

Método 1: Interfaz de n8n

Abre n8n: http://127.0.0.1:5678
Haz clic en Workflows → Import from File
Selecciona el archivo JSON de n8n-files/
Activa el flujo de trabajo

Método 2: CLI de Docker

# Copy workflow to n8n container
docker cp "n8n-files/AI Agent Safety Monitor - Updated.json" n8n:/files/workflow.json

# Import using n8n CLI
docker exec -it n8n n8n import:workflow --input=/files/workflow.json

# Verify import
docker exec -it n8n n8n list:workflow

Con Aplicaciones Web

Usa el transporte HTTP con tu cliente web compatible con MCP:

Inicia el servidor en modo HTTP
Configura el cliente para usar http://localhost:3000/mcp
Establece el transporte a Streamable HTTP (MCP 2025-03-26)
Habilita CORS agregando tu origen a MCP_HTTP_ALLOWED_ORIGINS

Con Proxy MCP Remoto (mcp-remote)

Conecta un cliente solo-stdio (Claude Desktop, LM Studio) a un servidor MCP HTTP remoto usando mcp-remote. En Windows, inícialo a través de cmd /c e incluye -y para que la primera ejecución nunca se bloquee en el mensaje de instalación de npx:

{
  "mcpServers": {
    "homeassistant": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://your-server.example/mcp",
        "--header",
        "Authorization: Bearer <your-jwt-token>"
      ]
    }
  }
}

⚠️ No uses marcadores de posición ${VAR} en el valor de --header. Una configuración como "Authorization: Bearer ${MCP_AUTH_TOKEN}" con un bloque env correspondiente no funciona en Windows: cmd /c solo expande %VAR% (no ${VAR}), y mcp-remote tampoco lo sustituye. El texto literal ${MCP_AUTH_TOKEN} se envía como token, el servidor responde 401, y mcp-remote cae en un flujo OAuth fallido que se muestra como "Server disconnected". Inserta el JWT real directamente. (En macOS/Linux puedes dejar que tu shell expanda la variable antes de que el cliente se inicie).

Notas de Configuración de Red

host.docker.internal - Úsalo para acceder a servicios en tu máquina host desde Docker
- Funciona en Windows y macOS por defecto
- En Linux, agrega --add-host=host.docker.internal:host-gateway a los argumentos de docker
IP Directa - Usa la dirección IP de tu máquina (por ejemplo, http://10.0.0.19:8123)
Dominios nip.io - Usa DNS comodín para desarrollo local fácil (por ejemplo, http://homeassistant.10.0.0.19.nip.io:8123)

Mejores Prácticas de Seguridad

Seguridad de Red

Segmentación de Red: Ejecuta el servidor MCP solo en LAN privada
Redes Docker: Usa redes Docker para aislamiento de contenedores
VLAN: Considera VLAN para dispositivos IoT
Sin Exposición a Internet: Nunca expongas el servidor MCP directamente a internet

Seguridad de Tokens y Configuración

Almacena .env de forma segura (contiene token de acceso)
Nunca hagas commit de .env al control de versiones
Establece permisos de .env: chmod 600 .env
Usa HA_STRICT_SSL=true para HTTPS en producción
Rota los tokens de acceso periódicamente
Restringe MCP_HTTP_ALLOWED_ORIGINS (evita el comodín *)
Vincula a 127.0.0.1 para acceso solo local
Habilita limitación de velocidad en producción (MCP_RATE_LIMIT_ENABLED=true)

Seguridad de Configuración del Cliente MCP

⚠️ Importante: Almacenar tokens directamente en archivos de configuración del cliente MCP (Claude Desktop, LM Studio) los expone a cualquier persona con acceso al sistema de archivos. Considera:

Usar archivos .env con permisos restringidos para implementaciones Docker/locales
Establecer permisos de archivo en los archivos de configuración (por ejemplo, chmod 600)
Usar sustitución de variables de entorno si tu cliente lo admite
Nunca hacer commit de archivos de configuración con tokens reales al control de versiones

Instrucciones del Servidor

El servidor proporciona Instrucciones del Servidor MCP durante la inicialización para ayudar a los LLMs a entender cómo usar óptimamente las herramientas disponibles. Las instrucciones se generan dinámicamente según los plugins habilitados e incluyen:

Consultas de Entidades: Orientación sobre paginación, inclusión de atributos y uso de herramientas especializadas como listPersons
Control de Dispositivos: Cuándo usar herramientas de control especializadas vs callService genérico
Flujos de Trabajo de Automatización: Mejores prácticas para crear y probar automatizaciones
Operaciones Omada: Requisitos de contexto del sitio, distinción entre cliente y dispositivo, seguridad de limitación de velocidad
Integración Entre Plugins: Cómo la detección de presencia de HA se correlaciona con los clientes de red Omada

Las instrucciones siguen las mejores prácticas de MCP: concisas, accionables y enfocadas en relaciones entre herramientas en lugar de repetir descripciones individuales de herramientas.

Solución de Problemas

Claude Desktop / LM Studio No Se Conecta

Verifica la ubicación del archivo de configuración - Confirma que estás editando el archivo correcto
Reinicia la aplicación - Cierra y vuelve a abrir después de cambios de configuración
Revisa los registros - Busca mensajes de error en los registros de la aplicación
Prueba la conexión manualmente:

# Test npx
npx @coffeerunhobby/mcp-ha-connect

# Test Docker
docker run --rm -i \
  -e HA_URL=http://homeassistant.10.0.0.19.nip.io:8123 \
  -e HA_TOKEN=your_token \
  ghcr.io/coffeerunhobby/mcp-ha-connect:latest

mcp-remote Muestra "Server disconnected" (401)

Si /health devuelve 200 pero el cliente muestra "Server disconnected", el encabezado de autenticación casi con certeza está mal formado. La causa más común: un marcador de posición ${VAR} en el valor de --header que nunca se expandió (ver la advertencia en Con Proxy MCP Remoto). Verifica que el endpoint acepte tu token directamente:

curl -i -X POST https://your-server.example/mcp \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"diag","version":"1.0"}}}'

Un 200 con un resultado initialize significa que el servidor y el token están bien — corrige la configuración del cliente (inserta el token literal). Un 401 significa que el token en sí es incorrecto.

Docker `host.docker.internal` No Funciona (Linux)

Agrega la puerta de enlace del host:

{
  "args": [
    "run",
    "--rm",
    "-i",
    "--add-host=host.docker.internal:host-gateway",
    "-e", "HA_URL=http://host.docker.internal:8123",
    ...
  ]
}

Problemas de Conexión con Home Assistant

Verifica la URL - Intenta acceder a http://your-ha-url:8123/api/ en el navegador
Revisa el token - Asegúrate de que sea un token de acceso de larga duración válido
Acceso de red - Verifica que el servidor MCP pueda alcanzar Home Assistant
Problemas SSL - Prueba con HA_STRICT_SSL=false para pruebas

El Análisis de IA No Funciona

Verifica que Ollama esté ejecutándose - curl http://your-ollama-url:11434/api/tags
Revisa que el modelo esté disponible - Asegúrate de que el modelo esté descargado: ollama pull llama2
Configura AI_PROVIDER - Debe estar configurado en ollama (no none)

Desarrollo

Configuración

# Clone repository
git clone https://github.com/coffeerunhobby/mcp-ha-connect.git
cd mcp-ha-connect

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your Home Assistant details
nano .env

# Build
npm run build

# Run
npm start

Scripts Disponibles

npm run build      # Build TypeScript to dist/
npm run dev        # Run in development mode with watch
npm start          # Run built version
npm test           # Run tests
npm run lint       # Run ESLint
npm run format     # Format code with Prettier

Licencia

MIT

Autor

Coffee Run Hobby (github.com/coffeerunhobby)

Enlaces

GitHub: https://github.com/coffeerunhobby/mcp-ha-connect
npm: https://www.npmjs.com/package/@coffeerunhobby/mcp-ha-connect
Docker: https://github.com/coffeerunhobby/mcp-ha-connect/pkgs/container/mcp-ha-connect

Documentación

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

MCP-HA-Connect

Documentación

MCP-HA-Connect

Características Principales

Funcionalidad Principal

Gestión de Automatizaciones

Características del Sistema

Monitoreo de Red y Seguridad (TP-Link Omada)

Herramientas Disponibles (69 en Total)

Herramientas de Home Assistant (38)

Herramientas de Estado y Entidades

Herramientas de Servicio y Control

Herramientas de Control de Dispositivos

Preguntas al Propietario (aprobación en el teléfono)

Herramientas de Automatización

Herramientas del Sistema

Herramientas de Calendario

Herramientas de Red Omada (49)

Herramientas de Sitio

Herramientas de Dispositivos

Herramientas de Clientes

Herramientas de Límite de Velocidad

Acciones de Clientes y Dispositivos

Diagnóstico de Clientes y Grupos MAC

Control de Acceso (horarios, grupos, ACL de puerta de enlace)

Herramientas de Seguridad

Herramientas de Configuración de Red

Herramientas de Red Independientes del Proveedor (9)

Herramientas de IA (1)

Recursos MCP

Requisitos Previos

Cómo Obtener su Token de Home Assistant

Variables de Entorno

Requeridas

Opcionales - Home Assistant

Opcionales - Servidor MCP

Opcionales - Modo HTTP

Opcionales - Interfaz de chat (superficie OpenAPI/REST)

Opcionales - Eventos SSE

Opcionales - Límite de Velocidad

Opcionales - Autenticación

Autenticación JWT

Sistema de Permisos

Opcionales - Proveedor de IA

Opcionales - Controlador de Red Omada

Ejemplos Avanzados de Configuración

Con Análisis de IA (Ollama)

Deshabilitar Funciones de IA

Docker con Configuración de Red

Modos de Uso

Modo 1: Cliente MCP (Claude Desktop / LM Studio)

Modo 2: Servidor HTTP

Transporte HTTP Transmisible

Suscripción a Eventos SSE

Modo 3: Docker Independiente

Modo 4: Docker Compose

Ejemplos de Integración

Con Claude Desktop

Con Flujos de Trabajo n8n

Importación de Flujos de Trabajo

Con Aplicaciones Web

Con Proxy MCP Remoto (mcp-remote)

Notas de Configuración de Red

Mejores Prácticas de Seguridad

Seguridad de Red

Seguridad de Tokens y Configuración

Seguridad de Configuración del Cliente MCP

Instrucciones del Servidor

Solución de Problemas

Claude Desktop / LM Studio No Se Conecta

mcp-remote Muestra "Server disconnected" (401)

Docker host.docker.internal No Funciona (Linux)

Problemas de Conexión con Home Assistant

El Análisis de IA No Funciona

Desarrollo

Configuración

Scripts Disponibles

Licencia

Autor

Enlaces

Docker `host.docker.internal` No Funciona (Linux)