local-home-devices-mcp

Servidor MCP (Model Context Protocol) para la gestión de dispositivos IoT. Permite a los asistentes de IA (Claude Desktop, LibreChat, Cline) descubrir y controlar dispositivos OpenBK (OpenBeken), Tasmota, Tuya, OpenHasp y HikVision en tu red local.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP Local Home Devices

Servidor MCP (Model Context Protocol) para gestión de dispositivos IoT. Permite a los asistentes de IA (Claude Desktop, LibreChat, Cline) descubrir y controlar dispositivos OpenBK (OpenBeken), Tasmota y Tuya en tu red local.

Requisitos

Docker (recomendado) o Python 3.11+ (para uso local)
Broker MQTT (opcional - solo necesario para herramientas MQTT)
Dispositivos OpenBK o Tasmota en la misma red local
Dispositivos Tuya (modelos WiFi; opcional - requiere credenciales de API en la nube de Tuya)
nmap - se instala automáticamente en Docker; para uso local, instala vía apt-get install nmap (puede requerir root/sudo)

Nota sobre redes: Docker usa el modo --network host para acceder a la red local donde se encuentran tus dispositivos IoT. Esto es necesario para el escaneo con nmap y la comunicación HTTP directa con los dispositivos.

Inicio Rápido

1. Configurar

cp .env.example .env
# Edit .env with your MQTT_BROKER and network range

2. Ejecutar con Docker

Opción A -- Imagen precompilada desde GitHub Container Registry:

docker run -d \
  --name local-home-devices-mcp \
  --network host \
  -e MQTT_BROKER=192.168.1.100 \
  -e START_IP=192.168.1.1 \
  -e END_IP=192.168.1.254 \
  -v local-home-devices-data:/app/data \
  ghcr.io/paulomac1000/local-home-devices-mcp:latest

Opción B -- con docker compose:

cp .env.example .env
# edit .env with your settings
docker compose up -d

Opción C -- Compilar localmente:

docker build -t local-home-devices-mcp .
docker run -d \
  --network host \
  -e MQTT_BROKER=192.168.1.100 \
  -e START_IP=192.168.1.1 \
  -e END_IP=192.168.1.254 \
  -v local-home-devices-data:/app/data \
  local-home-devices-mcp

3. Ejecutar localmente (Python 3.11+)

pip install -r requirements.txt
MQTT_BROKER=192.168.1.100 START_IP=192.168.1.1 END_IP=192.168.1.254 python server.py

Arquitectura

Puerto	Protocolo	Propósito	Endpoint
9100	HTTP	Verificación de salud	`GET /health`
9101	SSE	Transporte MCP	`/sse`, `/messages`
9102	HTTP	API REST	`/api/*`

Verificar

# Health check
curl http://localhost:9100/health

# List all MCP tools
curl http://localhost:9102/api/tools

# Call a tool via REST API
curl -X POST http://localhost:9102/api/tools/iot_list_devices \
  -H "Content-Type: application/json" \
  -d '{}'

Herramientas Disponibles

Descubrimiento de Dispositivos

Todas las operaciones de solo lectura - no se modifica el estado del dispositivo.

Herramienta	Riesgo	Descripción
`iot_discover_devices`	[LECTURA]	Escanear la red local en busca de dispositivos OpenBK y Tasmota
`iot_list_devices`	[LECTURA]	Listar todos los dispositivos descubiertos previamente desde la caché
`iot_check_device`	[LECTURA]	Verificación rápida de conectividad y estado para una IP específica
`iot_find_device_by_name`	[LECTURA]	Encontrar un dispositivo por su nombre descriptivo

Información del Dispositivo

Todas las operaciones de solo lectura - no se modifica el estado del dispositivo.

Herramienta	Riesgo	Descripción
`iot_get_device_info`	[LECTURA]	Información completa del dispositivo (nombre, firmware, tipo de chip, etc.)
`iot_get_device_power`	[LECTURA]	Estado de alimentación actual de un canal específico
`iot_get_wifi_config`	[LECTURA]	SSID WiFi, intensidad de señal RSSI, MAC, dirección IP

Control de Dispositivos

Herramienta	Riesgo	Descripción
`iot_set_power`	[ESCRITURA]	Encender, apagar o alternar un canal
`iot_set_brightness`	[ESCRITURA]	Establecer nivel de brillo (0-100%)
`iot_restart_device`	[DESTRUCTIVO]	Reiniciar el dispositivo (se desconecta temporalmente)

Configuración de Dispositivos

Herramienta	Riesgo	Descripción
`iot_set_flags`	[ESCRITURA]	Establecer banderas de configuración del dispositivo como campo de bits (OpenBK /cfg_generic, Tasmota SetOption)
`iot_set_name`	[ESCRITURA]	Establecer nombre corto y completo del dispositivo (OpenBK vía /cfg_name)
`iot_configure_mqtt`	[ESCRITURA]	Configurar conexión al broker MQTT (OpenBK vía /cfg_mqtt_set)
`iot_set_gpio`	[ESCRITURA]	Configurar rol de pin GPIO y canal (OpenBK vía /cfg_pins)
`iot_execute_command`	[DESTRUCTIVO]	Ejecutar comando crudo /cm?cmnd= con protección de comandos bloqueados
`iot_start_ha_discovery`	[ESCRITURA]	Activar descubrimiento MQTT de Home Assistant (OpenBK vía /ha_discovery)
`iot_get_full_info`	[LECTURA]	Información mejorada del dispositivo: MAC, versión, banderas, MQTT, WiFi (tanto OpenBK como Tasmota)

Introspección

Herramienta	Riesgo	Descripción
`describe_iot_capabilities`	[LECTURA]	Describir todas las herramientas IoT, manifiestos y transportes

Integración MQTT

Herramienta	Riesgo	Descripción
`iot_mqtt_publish`	[ESCRITURA]	Publicar un comando vía MQTT
`iot_mqtt_get_state`	[LECTURA]	Obtener estado del dispositivo desde el broker MQTT
`iot_mqtt_build_command_topic`	[LECTURA]	Construir tema de comando MQTT para un dispositivo

Paneles OpenHASP

Herramienta	Riesgo	Descripción
`openhasp_detect`	[LECTURA]	Verificar si una IP es un panel OpenHASP
`openhasp_status`	[LECTURA]	Estado completo del panel: versión, retroiluminación, objetos, heap, WiFi
`openhasp_check_backlight`	[LECTURA]	Analizar retroiluminación para problemas comunes
`openhasp_get_config`	[LECTURA]	Obtener config.json completo del panel
`openhasp_get_pages`	[LECTURA]	Obtener pages.jsonl con conteos de objetos/páginas
`openhasp_screenshot`	[LECTURA]	Capturar y descargar screenshot.bmp
`openhasp_download_file`	[LECTURA]	Descargar cualquier archivo config/cmd del panel
`openhasp_upload_file`	[ESCRITURA]	Subir un archivo vía POST /edit
`openhasp_ota_update`	[DESTRUCTIVO]	Actualización de firmware OTA vía URL
`openhasp_page_set`	[ESCRITURA]	Navegar a una página específica
`openhasp_jsonl_send`	[ESCRITURA]	Enviar JSONL para crear/modificar objetos de interfaz
`openhasp_telnet`	[ESCRITURA]	Enviar comando Telnet crudo (TCP crudo, sin telnetlib)
`openhasp_backlight_set`	[ESCRITURA]	Establecer estado y brillo de retroiluminación
`openhasp_config_set`	[ESCRITURA]	Configuración en tiempo de ejecución vía Telnet config/gui
`openhasp_idle_reset`	[ESCRITURA]	Restablecer temporizador de inactividad para activar pantalla
`openhasp_restart`	[DESTRUCTIVO]	Reiniciar el panel
`openhasp_factory_reset`	[DESTRUCTIVO]	Restablecimiento de fábrica (solo EEPROM, los archivos sobreviven)
`openhasp_validate_config`	[LECTURA]	Validar configuración para problemas comunes
`openhasp_health`	[LECTURA]	Puntuación compuesta de salud 0-100
`openhasp_hardware_test`	[ESCRITURA]	Secuencia de diagnóstico automatizada

Videoportero Hikvision

Herramienta	Riesgo	Descripción
`hikvision_container_status`	[LECTURA]	[CONTENEDOR] Obtener estado de ejecución y salud del contenedor Docker
`hikvision_container_logs`	[LECTURA]	[CONTENEDOR] Obtener registros recientes del contenedor (eventos VMD, llamadas, errores)
`hikvision_device_info`	[LECTURA]	Obtener metadatos del dispositivo videoportero vía ISAPI
`hikvision_check_vmd`	[LECTURA]	[CONTENEDOR] Verificar eventos de movimiento VMD -- canario de salud ISAPI
`hikvision_take_snapshot`	[LECTURA]	Capturar instantánea JPEG de la cámara del videoportero
`hikvision_get_motion_config`	[LECTURA]	Obtener configuración de detección de movimiento VMD
`hikvision_get_event_config`	[LECTURA]	Obtener configuración de disparadores de eventos ISAPI
`hikvision_get_alarm_server`	[LECTURA]	Obtener configuración del host de notificación HTTP (servidor de alarma)
`hikvision_isapi_health`	[LECTURA]	[CONTENEDOR] Verificación de salud compuesta (contenedor + VMD + eventos de llamada)
`hikvision_pipeline_diagnose`	[LECTURA]	[CONTENEDOR] Trazado completo de pipeline (contenedor a ISAPI a eventos a MQTT a instantáneas)
`hikvision_open_gate`	[ESCRITURA]	Activar relé de cerradura eléctrica para abrir la puerta
`hikvision_set_motion_detection`	[ESCRITURA]	Activar/desactivar VMD o ajustar sensibilidad (con protección de escritura)
`hikvision_snapshot_to_file`	[ESCRITURA]	Capturar JPEG y guardar directamente en disco (con protección de escritura)
`hikvision_restart_container`	[DESTRUCTIVO]	[CONTENEDOR] Reiniciar el contenedor Docker

Nota: Las herramientas marcadas con [CONTAINER] requieren el contenedor Docker hikvision-doorbell y acceso a /var/run/docker.sock. Las herramientas solo-ISAPI funcionan con cualquier videoportero Hikvision accesible vía autenticación HTTP Digest.

Configuración

Toda la configuración se realiza mediante variables de entorno. Consulta .env.example para una plantilla completa.

Requerido para herramientas MQTT (opcional en otros casos)

Variable	Descripción	Ejemplo
`MQTT_BROKER`	Dirección IP del broker MQTT	`192.168.1.100`

Consejo: Sin broker MQTT, el descubrimiento de dispositivos y el control HTTP siguen funcionando. Establece MQTT_BROKER solo si necesitas herramientas basadas en MQTT (iot_mqtt_publish, iot_mqtt_get_state, etc.).

Escaneo de Red

Variable	Predeterminado	Descripción
`START_IP`	`192.168.1.1`	Primera IP en el rango de escaneo
`END_IP`	`192.168.1.254`	Última IP en el rango de escaneo
`NETWORK_RANGE`	`192.168.1.0/24`	Rango CIDR para escaneo nmap (anula START_IP/END_IP si se establece)

Opcional

Variable	Predeterminado	Descripción
`ENABLE_WRITE_OPERATIONS`	`0`	Establecer en `1` para habilitar herramientas de escritura/destructivas (set_power, restart, etc.)
`MQTT_PORT`	`1883`	Puerto del broker MQTT
`MQTT_USER`	--	Nombre de usuario MQTT
`MQTT_PASSWORD`	--	Contraseña MQTT
`MCP_SSE_PORT`	`9101`	Puerto de transporte SSE MCP
`REST_API_PORT`	`9102`	Puerto de API REST

Estructura del Proyecto

tools/constants.py - Todos los valores predeterminados de configuración compartidos (sin IPs codificadas en archivos de herramientas)
tools/validators.py - Validación de entrada para parámetros de herramientas
tools/iot_control.py - Control de alimentación/brillo/reinicio/WiFi (4 herramientas)
tools/iot_devices.py - Información del dispositivo/estado de alimentación (2 herramientas)
tools/iot_discovery.py - Escaneo de red/descubrimiento de dispositivos/caché (4 herramientas)
tools/iot_mqtt.py - Publicación/estado/tema MQTT (3 herramientas)
tools/iot_meta.py - Introspección de capacidades, manifiestos y transportes (1 herramienta)
tools/iot_tuya.py - Control en nube + local de dispositivos Tuya + diagnósticos (10 herramientas)
tools/iot_openhasp.py - Control de paneles OpenHASP, diagnósticos, Telnet (20 herramientas)
tools/openhasp/ - Asistentes HTTP, Telnet y diagnósticos OpenHASP
tools/iot_config.py - Herramientas de configuración de dispositivos (7 herramientas)
tools/iot_hikvision.py - Herramientas de videoportero Hikvision (14 herramientas)
tools/hikvision/ - Cliente HTTP ISAPI, asistente de socket Docker
tools/http_session.py - Módulo de cliente HTTP genérico para dispositivos IoT

Dispositivos Compatibles

OpenBK (OpenBeken)

Chips: BK7231N, BK7231T, XR809, BL602
Dispositivos: Luces, interruptores, cortinas, sensores
Detección: HTTP GET /index devuelve HTML que contiene "openbeken"

Tasmota

Chips: ESP8266, ESP32
Dispositivos: Luces, interruptores, sensores, ventiladores, enchufes
Detección: HTTP GET /cm?cmnd=Status devuelve JSON con clave "Status"

Tuya

Chips: ESP8266, ESP32, BK7231N/T (varía según el fabricante)
Dispositivos: Aspiradoras, hervidores, válvulas de agua, sensores, pasarelas
Detección: Puerto TCP 6668 abierto en la red local
Requisitos: Credenciales de API en la nube de Tuya (Access ID, Access Secret) para recuperación de clave local
Protocolo: TCP/UDP cifrado vía biblioteca tinytuya, respaldo de API en la nube

OpenHASP

Chips: ESP32 (WT32-SC01, WT32-SC01 Plus, ESP32-S3)
Dispositivos: Pantallas táctiles, paneles de control montados en pared, paneles de control
Detección: HTTP GET /config.json devuelve JSON con clave "hasp"
Protocolo: API HTTP para configuración/archivos + Telnet TCP crudo para control (NO telnetlib)
Telnet: Usa socket TCP crudo - formato PUB MQTT cuando está conectado a MQTT, formato MSGR en otros casos

Videoportero Hikvision

Modelos: DS-KV6113-WPE1(C), DS-KV8113-WPE1(C), serie VillaVTO
Características: Instantánea de cámara, detección de movimiento (VMD), control de puerta, disparadores de eventos, salud ISAPI
Detección: El contenedor Docker hikvision-doorbell gestiona la conexión ISAPI
Protocolo: Autenticación HTTP Digest ISAPI + API de socket Unix Docker
Requisitos: Contenedor Docker hikvision-doorbell, credenciales ISAPI (HIKVISION_DOORBELL_HOST/USER/PASSWORD)

Pruebas

El proyecto tiene una jerarquía de pruebas de 4 niveles (consulta AGENTS.md para detalles):

Suite	Pruebas	Cobertura	Comando
Unitarias	378	>80%	`pytest tests/unit/ -v --tb=short`
Integración	25	66%	`pytest tests/integration/ -q`
Smoke	25	Validación HTTP	`pytest tests/smoke/ -q`
E2E	9	Validación HTTP	`pytest tests/e2e/ -q`

Las pruebas unitarias se ejecutan en CI. Las pruebas de integración, smoke y e2e se omiten cuando sus dependencias (broker MQTT, servidor en ejecución) están ausentes.

El servidor sigue los Estándares de Servidor MCP en nivel de madurez L2/L3.

Configuración de Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "local-home-devices": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9101/sse"]
    }
  }
}

Licencia

MIT -- consulta LICENSE para detalles.