local-home-devices-mcp

Servidor MCP (Model Context Protocol) para gerenciamento de dispositivos IoT. Permite que assistentes de IA (Claude Desktop, LibreChat, Cline) descubram e controlem dispositivos OpenBK (OpenBeken), Tasmota, Tuya, OpenHasp e HikVision em sua rede local.

GitHub

Experimente este MCPPatrocinado

Documentação

Local Home Devices MCP

Requisitos

Docker (recomendado) ou Python 3.11+ (para uso local)
Broker MQTT (opcional - necessário apenas para ferramentas MQTT)
Dispositivos OpenBK ou Tasmota na mesma rede local
Dispositivos Tuya (modelos WiFi; opcional - requer credenciais da API de nuvem Tuya)
nmap - instalado automaticamente no Docker; para uso local, instale via apt-get install nmap (pode exigir root/sudo)

Nota sobre rede: O Docker usa o modo --network host para acessar a rede local onde seus dispositivos IoT estão localizados. Isso é necessário para o escaneamento nmap e comunicação HTTP direta com os dispositivos.

Início Rápido

1. Configure

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

2. Execute com Docker

Opção A -- Imagem pré-construída do 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

Opção B -- com docker compose:

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

Opção C -- Compile 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. Execute 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

Arquitetura

Porta	Protocolo	Finalidade	Endpoint
9100	HTTP	Verificação de saúde	`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 '{}'

Ferramentas Disponíveis

Descoberta de Dispositivos

Todas as operações somente leitura - nenhum estado de dispositivo é modificado.

Ferramenta	Risco	Descrição
`iot_discover_devices`	[READ]	Escanear a rede local em busca de dispositivos OpenBK e Tasmota
`iot_list_devices`	[READ]	Listar todos os dispositivos descobertos anteriormente a partir do cache
`iot_check_device`	[READ]	Verificação rápida de conectividade e status para um IP específico
`iot_find_device_by_name`	[READ]	Encontrar um dispositivo pelo seu nome amigável

Informações do Dispositivo

Todas as operações somente leitura - nenhum estado de dispositivo é modificado.

Ferramenta	Risco	Descrição
`iot_get_device_info`	[READ]	Informações completas do dispositivo (nome, firmware, tipo de chip, etc.)
`iot_get_device_power`	[READ]	Estado de energia atual de um canal específico
`iot_get_wifi_config`	[READ]	SSID WiFi, intensidade do sinal RSSI, MAC, endereço IP

Controle de Dispositivos

Ferramenta	Risco	Descrição
`iot_set_power`	[WRITE]	Ligar, desligar ou alternar (TOGGLE) um canal
`iot_set_brightness`	[WRITE]	Definir nível de brilho (0-100%)
`iot_restart_device`	[DESTRUCTIVE]	Reiniciar o dispositivo (desconecta temporariamente)

Configuração de Dispositivos

Ferramenta	Risco	Descrição
`iot_set_flags`	[WRITE]	Definir flags de configuração do dispositivo como bitfield (OpenBK /cfg_generic, Tasmota SetOption)
`iot_set_name`	[WRITE]	Definir nome curto e completo do dispositivo (OpenBK via /cfg_name)
`iot_configure_mqtt`	[WRITE]	Configurar conexão com broker MQTT (OpenBK via /cfg_mqtt_set)
`iot_set_gpio`	[WRITE]	Configurar função do pino GPIO e canal (OpenBK via /cfg_pins)
`iot_execute_command`	[DESTRUCTIVE]	Executar comando bruto /cm?cmnd= com segurança de comando bloqueado
`iot_start_ha_discovery`	[WRITE]	Acionar descoberta MQTT do Home Assistant (OpenBK via /ha_discovery)
`iot_get_full_info`	[READ]	Informações aprimoradas do dispositivo: MAC, versão, flags, MQTT, WiFi (OpenBK e Tasmota)

Introspecção

Ferramenta	Risco	Descrição
`describe_iot_capabilities`	[READ]	Descrever todas as ferramentas IoT, manifestos e transportes

Integração MQTT

Ferramenta	Risco	Descrição
`iot_mqtt_publish`	[WRITE]	Publicar um comando via MQTT
`iot_mqtt_get_state`	[READ]	Obter estado do dispositivo a partir do broker MQTT
`iot_mqtt_build_command_topic`	[READ]	Construir tópico de comando MQTT para um dispositivo

Painéis OpenHASP

Ferramenta	Risco	Descrição
`openhasp_detect`	[READ]	Verificar se um IP é um painel OpenHASP
`openhasp_status`	[READ]	Status completo do painel: versão, retroiluminação, objetos, heap, WiFi
`openhasp_check_backlight`	[READ]	Analisar retroiluminação para problemas comuns
`openhasp_get_config`	[READ]	Obter config.json completo do painel
`openhasp_get_pages`	[READ]	Obter pages.jsonl com contagens de objetos/páginas
`openhasp_screenshot`	[READ]	Capturar e baixar screenshot.bmp
`openhasp_download_file`	[READ]	Baixar qualquer arquivo config/cmd do painel
`openhasp_upload_file`	[WRITE]	Enviar um arquivo via POST /edit
`openhasp_ota_update`	[DESTRUCTIVE]	Atualização de firmware OTA via URL
`openhasp_page_set`	[WRITE]	Navegar para uma página específica
`openhasp_jsonl_send`	[WRITE]	Enviar JSONL para criar/modificar objetos de interface
`openhasp_telnet`	[WRITE]	Enviar comando Telnet bruto (TCP bruto, sem telnetlib)
`openhasp_backlight_set`	[WRITE]	Definir estado e brilho da retroiluminação
`openhasp_config_set`	[WRITE]	Configuração em tempo de execução via Telnet config/gui
`openhasp_idle_reset`	[WRITE]	Redefinir temporizador de inatividade para ativar a tela
`openhasp_restart`	[DESTRUCTIVE]	Reiniciar o painel
`openhasp_factory_reset`	[DESTRUCTIVE]	Restauração de fábrica (apenas EEPROM, arquivos são preservados)
`openhasp_validate_config`	[READ]	Validar configuração para problemas comuns
`openhasp_health`	[READ]	Pontuação composta de saúde 0-100
`openhasp_hardware_test`	[WRITE]	Sequência de diagnóstico automatizada

Campainha Hikvision

Ferramenta	Risco	Descrição
`hikvision_container_status`	[READ]	[CONTAINER] Obter status de execução e saúde do contêiner Docker
`hikvision_container_logs`	[READ]	[CONTAINER] Obter logs recentes do contêiner (eventos VMD, chamadas, erros)
`hikvision_device_info`	[READ]	Obter metadados do dispositivo de campainha via ISAPI
`hikvision_check_vmd`	[READ]	[CONTAINER] Verificar eventos de movimento VMD -- canário de saúde ISAPI
`hikvision_take_snapshot`	[READ]	Capturar snapshot JPEG da câmera da campainha
`hikvision_get_motion_config`	[READ]	Obter configuração de detecção de movimento VMD
`hikvision_get_event_config`	[READ]	Obter configuração de gatilho de eventos ISAPI
`hikvision_get_alarm_server`	[READ]	Obter configuração do host de notificação HTTP (servidor de alarme)
`hikvision_isapi_health`	[READ]	[CONTAINER] Verificação de saúde composta (contêiner + VMD + eventos de chamada)
`hikvision_pipeline_diagnose`	[READ]	[CONTAINER] Rastreamento completo do pipeline (contêiner para ISAPI para eventos para MQTT para snapshots)
`hikvision_open_gate`	[WRITE]	Acionar relé da fechadura elétrica para abrir o portão
`hikvision_set_motion_detection`	[WRITE]	Ativar/desativar VMD ou ajustar sensibilidade (protegido contra escrita)
`hikvision_snapshot_to_file`	[WRITE]	Capturar JPEG e salvar diretamente no disco (protegido contra escrita)
`hikvision_restart_container`	[DESTRUCTIVE]	[CONTAINER] Reiniciar o contêiner Docker

Nota: Ferramentas marcadas com [CONTAINER] exigem o contêiner Docker hikvision-doorbell e acesso a /var/run/docker.sock. Ferramentas somente ISAPI funcionam com qualquer campainha Hikvision acessível via HTTP Digest Auth.

Configuração

Toda a configuração é feita por variáveis de ambiente. Consulte .env.example para um modelo completo.

Necessário para ferramentas MQTT (opcional caso contrário)

Variável	Descrição	Exemplo
`MQTT_BROKER`	Endereço IP do broker MQTT	`192.168.1.100`

Dica: Sem broker MQTT, a descoberta de dispositivos e o controle HTTP ainda funcionam. Defina MQTT_BROKER apenas se precisar de ferramentas baseadas em MQTT (iot_mqtt_publish, iot_mqtt_get_state, etc.).

Escaneamento de Rede

Variável	Padrão	Descrição
`START_IP`	`192.168.1.1`	Primeiro IP no intervalo de escaneamento
`END_IP`	`192.168.1.254`	Último IP no intervalo de escaneamento
`NETWORK_RANGE`	`192.168.1.0/24`	Intervalo CIDR para escaneamento nmap (substitui START_IP/END_IP se definido)

Opcional

Variável	Padrão	Descrição
`ENABLE_WRITE_OPERATIONS`	`0`	Defina como `1` para habilitar ferramentas de escrita/destrutivas (set_power, restart, etc.)
`MQTT_PORT`	`1883`	Porta do broker MQTT
`MQTT_USER`	--	Nome de usuário MQTT
`MQTT_PASSWORD`	--	Senha MQTT
`MCP_SSE_PORT`	`9101`	Porta de transporte SSE MCP
`REST_API_PORT`	`9102`	Porta da API REST

Estrutura do Projeto

tools/constants.py - Todos os padrões de configuração compartilhados (sem IPs codificados nos arquivos de ferramentas)
tools/validators.py - Validação de entrada para parâmetros de ferramentas
tools/iot_control.py - Controle de energia/brilho/reinicialização/WiFi (4 ferramentas)
tools/iot_devices.py - Informações do dispositivo/estado de energia (2 ferramentas)
tools/iot_discovery.py - Escaneamento de rede/descoberta de dispositivos/cache (4 ferramentas)
tools/iot_mqtt.py - Publicação/estado/tópico MQTT (3 ferramentas)
tools/iot_meta.py - Introspecção de capacidades, manifestos e transportes (1 ferramenta)
tools/iot_tuya.py - Nuvem de dispositivos Tuya + controle local + diagnósticos (10 ferramentas)
tools/iot_openhasp.py - Controle de painel OpenHASP, diagnósticos, Telnet (20 ferramentas)
tools/openhasp/ - Auxiliares HTTP, Telnet e diagnósticos OpenHASP
tools/iot_config.py - Ferramentas de configuração de dispositivos (7 ferramentas)
tools/iot_hikvision.py - Ferramentas de campainha Hikvision (14 ferramentas)
tools/hikvision/ - Cliente HTTP ISAPI, auxiliar de socket Docker
tools/http_session.py - Módulo de cliente HTTP genérico para dispositivos IoT

Dispositivos Suportados

OpenBK (OpenBeken)

Chips: BK7231N, BK7231T, XR809, BL602
Dispositivos: Luzes, interruptores, cortinas, sensores
Detecção: HTTP GET /index retorna HTML contendo "openbeken"

Tasmota

Chips: ESP8266, ESP32
Dispositivos: Luzes, interruptores, sensores, ventiladores, tomadas
Detecção: HTTP GET /cm?cmnd=Status retorna JSON com chave "Status"

Tuya

Chips: ESP8266, ESP32, BK7231N/T (varia conforme o fabricante)
Dispositivos: Aspiradores, chaleiras, válvulas de água, sensores, gateways
Detecção: Porta TCP 6668 aberta na rede local
Requisitos: Credenciais da API de nuvem Tuya (Access ID, Access Secret) para recuperação de chave local
Protocolo: TCP/UDP criptografado via biblioteca tinytuya, fallback de API de nuvem

OpenHASP

Chips: ESP32 (WT32-SC01, WT32-SC01 Plus, ESP32-S3)
Dispositivos: Telas de painel touch, painéis de controle montados na parede, painéis de controle
Detecção: HTTP GET /config.json retorna JSON com chave "hasp"
Protocolo: API HTTP para config/arquivos + Telnet TCP bruto para controle (NÃO telnetlib)
Telnet: Usa socket TCP bruto - formato MQTT PUB quando conectado via MQTT, formato MSGR caso contrário

Campainha Hikvision

Modelos: DS-KV6113-WPE1(C), DS-KV8113-WPE1(C), série VillaVTO
Recursos: Snapshot de câmera, detecção de movimento (VMD), controle de portão, gatilhos de eventos, saúde ISAPI
Detecção: O contêiner Docker hikvision-doorbell gerencia a conexão ISAPI
Protocolo: ISAPI HTTP Digest Auth + API de socket Unix Docker
Requisitos: Contêiner Docker hikvision-doorbell, credenciais ISAPI (HIKVISION_DOORBELL_HOST/USER/PASSWORD)

Testes

O projeto tem uma hierarquia de testes em 4 níveis (consulte AGENTS.md para detalhes):

Suíte	Testes	Cobertura	Comando
Unitário	378	>80%	`pytest tests/unit/ -v --tb=short`
Integração	25	66%	`pytest tests/integration/ -q`
Smoke	25	Validação HTTP	`pytest tests/smoke/ -q`
E2E	9	Validação HTTP	`pytest tests/e2e/ -q`

Os testes unitários são executados no CI. Os testes de integração, smoke e e2e são ignorados quando suas dependências (broker MQTT, servidor em execução) estão ausentes.

O servidor segue os Padrões de Servidor MCP no nível de maturidade L2/L3.

Configuração do Claude Desktop

Adicione ao seu claude_desktop_config.json:

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

Licença

MIT -- consulte LICENSE para detalhes.