MCP-HA-Connect

Um servidor Model Context Protocol (MCP) pronto para produção, para integração do Home Assistant com assistentes de IA como o Claude.

GitHub

Documentação

MCP-HA-Connect

Um servidor Model Context Protocol (MCP) pronto para produção, para integração do Home Assistant com assistentes de IA como Claude e LM Studio.

Consulte docs/QUICK_START.md para Docker, modo de servidor HTTP, integração com n8n e mais opções de instalação.

Principais Recursos

Funcionalidade Principal

Controle Inteligente de Dispositivos
Luzes: Brilho, temperatura de cor, cor RGB, transições
Clima: Temperatura, modos HVAC, modos de ventilador, umidade
Coberturas: Controle de posição e inclinação
Interruptores: Controle liga/desliga
Sensores e Contatos: Monitoramento de estado
Players de Mídia: Controle de reprodução, volume, seleção de fonte
Ventiladores: Velocidade, oscilação, direção
Fechaduras: Controle de travar/destravar
Aspiradores: Iniciar, parar, retornar à base
Câmeras: Detecção de movimento, instantâneos

Gerenciamento de Automações

Listar todas as automações com status
Acionar automações manualmente com variáveis
Ativar/desativar/alternar automações
Criar novas automações via API
Excluir automações
Visualizar rastros de execução de automações
Recarregar automações a partir da configuração

Recursos do Sistema

Integração direta com a API do Home Assistant
Autenticação por token de acesso de longa duração
Gerenciamento de estado de entidades
Suporte a chamadas de serviço
Busca avançada de entidades
Análise de sensores com IA usando Ollama
Múltiplos modos de transporte (stdio, HTTP Streamable)
Servidor HTTP com verificações de saúde
Suporte a CORS para clientes baseados em navegador
Logs estruturados (formatos plain, JSON, GCP-JSON)
Validação abrangente de configuração com Zod
Segurança total de tipos com TypeScript
Suporte a sessões com e sem estado
Autenticação JWT com controle de acesso baseado em papéis
Instruções do Servidor MCP para melhor seleção de ferramentas por LLMs

Monitoramento de Rede e Segurança (TP-Link Omada)

Traga sua rede doméstica para o mesmo assistente que gerencia sua casa. Estas são as perguntas de alto valor que um LLM pode realmente responder sobre sua rede:

Status de Internet e WAN — "Minha internet está no ar? Qual é meu IP de WAN e velocidade de uplink?" Status ao vivo por WAN, além de saúde multi-WAN / ISP e balanceamento de carga para o gateway.
Logs de eventos e alertas — "O que aconteceu na minha rede?" Os logs de eventos e alertas do site, com janela de tempo (padrão dos últimos 7 dias), para correlacionar com o histórico do Home Assistant.
Segurança sem fio — resultados de varredura de APs rogue e (no Omada Pro) detecção de intrusão sem fio (WIDS) para conscientização real de segurança de rede.
Saúde do controlador e dos dispositivos — visão geral do painel, além dos principais dispositivos por uso de CPU e memória, monitoramento estilo HA da sua pilha de rede.
Testes de velocidade — apresentar os resultados de teste de velocidade do próprio controlador, combinando com analyzeSensors com IA para detecção de anomalias.
Dispositivos pendentes — "Há um novo dispositivo aguardando adoção?"
Consciência de firmware — informações de firmware por dispositivo e uma visão geral de atualizações críticas em todo o controlador, espelhando a filosofia do checkUpdates do Home Assistant em toda a rede.
Gerenciamento de clientes — listar/inspecionar clientes conectados, atividade de tráfego e aplicar perfis de limite de taxa, com correlação de presença com os rastreadores de dispositivos do Home Assistant.

Um modo de grafo de recursos descobrível (MCP_TOOL_REGISTRATION_MODE=graph) expõe tudo o que foi mencionado acima por meio de duas ferramentas — omada_browse + omada_read — mantendo o orçamento de esquema de ferramentas pequeno para modelos de baixo contexto. Consulte as tabelas de ferramentas Omada abaixo para a superfície completa.

Ferramentas Disponíveis (69 no Total)

Ferramentas do Home Assistant (38)

Ferramentas de Estado e Entidade

Ferramenta	Descrição
`getStates`	Obter todos os estados de entidades (paginado, 50/página por padrão). Use `includeAttributes=true` para dados completos
`getState`	Obter o estado de uma entidade específica por entity_id
`getEntitiesByDomain`	Obter entidades de um domínio (paginado, 50/página por padrão). Use `includeAttributes=true` para dados completos
`searchEntities`	Buscar entidades por nome/entity_id (paginado, 50/página por padrão). Use `includeAttributes=true` para dados completos
`getAllSensors`	Obter todos os sensores (paginado, 50/página por padrão). Use `includeAttributes=true` para dados completos
`listEntities`	Listar entidades com filtros (domínio, estado, busca, limite). Use `includeAttributes=true` para dados completos
`getDomainSummary`	Obter estatísticas resumidas para um domínio
`getHistory`	Obter dados históricos de uma entidade
`listPersons`	Listar todos os membros da casa com estado de localização (em casa/fora)

Ferramentas de Serviço e Controle

Ferramenta	Descrição
`callService`	Chamar qualquer serviço do Home Assistant
`entityAction`	Ações simples de ligar/desligar/alternar

Ferramentas de Controle de Dispositivos

Ferramenta	Descrição
`controlLight`	Controlar luzes com brilho, cor, temperatura
`controlClimate`	Controlar termostatos com temperatura, modo HVAC
`controlMediaPlayer`	Controlar players de mídia com reprodução, volume
`controlCover`	Controlar coberturas/persianas com posição, inclinação
`controlFan`	Controlar ventiladores com velocidade, oscilação, direção
`activateScene`	Ativar uma cena do Home Assistant
`runScript`	Executar um script do Home Assistant
`sendNotification`	Enviar notificações com suporte completo ao aplicativo móvel (ações, prioridade, imagens)
`listNotificationTargets`	Descobrir alvos de notificação disponíveis no aplicativo móvel

Perguntas ao Proprietário (aprovação no telefone)

Faça uma pergunta ao proprietário como uma notificação no telefone com até 3 botões e leia a resposta. Somente no modo HTTP; requer um token do Home Assistant admin (toques em botões são eventos somente de admin) e MCP_AUTH_SECRET para que perguntas abertas sobrevivam a uma reinicialização. Tudo, exceto uma resposta de aprovação explícita, conta como NÃO.

Ferramenta	Descrição
`askOwner`	Enviar a pergunta (texto simples, máximo 256 caracteres; 1-3 botões, padrão Aprovar / Negar; aberta por até 7 dias) e retornar um `requestId` imediatamente
`getOwnerAnswer`	Aguardar até 50 s por chamada: `answered` (índice e rótulo do botão, hora, usuário do HA), `pending`, `timeout`, `cancelled` ou `unknown`
`cancelOwnerQuestion`	Retirar uma pergunta aberta; a notificação muda para "Cancelada"

Os toques são verificados com IDs de botão assinados e devem vir do aplicativo móvel (uma automação não pode falsificá-los); defina MCP_OWNER_QUESTIONS_HA_USERS para que apenas seu usuário do HA possa responder. Somente o cliente que perguntou pode ler a resposta; no máximo 3 perguntas abertas e 30 por hora por cliente.

Limite conhecido: cancelamentos e respostas são mantidos em memória. Após uma reinicialização, alguém com login no Home Assistant poderia reenviar um ID de botão antigo pela própria API do HA e responder a uma pergunta que havia sido cancelada ou negada (o telefone não mostra mais os botões). Esse acesso já permite controlar a casa diretamente.

Ferramentas de Automação

Ferramenta	Descrição
`listAutomations`	Listar todas as automações com status
`triggerAutomation`	Acionar uma automação manualmente
`enableAutomation`	Ativar uma automação desativada
`disableAutomation`	Desativar uma automação
`toggleAutomation`	Alternar o estado de uma automação
`reloadAutomations`	Recarregar automações a partir da configuração
`createAutomation`	Criar uma nova automação
`deleteAutomation`	Excluir uma automação
`getAutomationTrace`	Execuções recentes de uma automação, mais recentes primeiro: gatilho, resultado, erros (somente automações com `id`)

Ferramentas do Sistema

Ferramenta	Descrição
`getVersion`	Obter versão do Home Assistant e informações de configuração
`restartHomeAssistant`	Reiniciar o servidor do Home Assistant
`getSystemLog`	Obter entradas de log do sistema a partir do logbook
`checkUpdates`	Verificar atualizações disponíveis

Ferramentas de Calendário

Ferramenta	Descrição
`listCalendars`	Listar todas as entidades de calendário
`getCalendarEvents`	Obter eventos de um ou de todos os calendários

Ferramentas Omada de Rede (49)

Ferramentas de Site

Ferramenta	Descrição
`omada_listSites`	Listar todos os sites configurados no controlador Omada

Ferramentas de Dispositivos

Ferramenta	Descrição
`omada_listDevices`	Listar todos os dispositivos de rede (APs, switches, gateways) em um site
`omada_getDevice`	Obter informações detalhadas sobre um dispositivo de rede específico
`omada_searchDevices`	Buscar dispositivos globalmente em todos os sites
`omada_getSwitchStackDetail`	Obter informações detalhadas sobre uma pilha de switches
`omada_listDevicesStats`	Obter estatísticas para dispositivos adotados globalmente com filtros

Ferramentas de Clientes

Ferramenta	Descrição
`omada_listClients`	Listar todos os clientes conectados (dispositivos/usuários) em um site
`omada_getClient`	Obter informações detalhadas sobre um cliente conectado específico
`omada_listMostActiveClients`	Obter os clientes mais ativos ordenados por tráfego total
`omada_listClientsActivity`	Obter estatísticas de atividade de clientes ao longo do tempo
`omada_listClientsPastConnections`	Obter dados históricos de conexão de clientes

Ferramentas de Limite de Taxa

Ferramenta	Descrição
`omada_getRateLimitProfiles`	Obter perfis de limite de taxa disponíveis para um site
`omada_setClientRateLimit`	Definir limites de largura de banda personalizados para um cliente (download/upload em Kbps)
`omada_setClientRateLimitProfile`	Aplicar um perfil de limite de taxa a um cliente
`omada_disableClientRateLimit`	Remover limites de largura de banda de um cliente

Ações de Clientes e Dispositivos

Ferramenta	Descrição
`omada_blockClient`	Bloquear um cliente da rede
`omada_unblockClient`	Desbloquear um cliente previamente bloqueado (explica quando a API do Omada não consegue mais alcançar um cliente offline)
`omada_listBlockedClients`	Listar clientes bloqueados, incluindo os offline
`omada_deleteClient`	Excluir o registro de um cliente (nome, histórico, bloqueio) para limpar um bloqueio que o desbloqueio não alcança (requer `CONFIGURE`)
`omada_cyclePoePort`	Ciclar energia das portas PoE do switch (reinicialização remota de APs/câmeras)
`omada_setSsidEnabled`	Ligar ou desligar um SSID (ex.: WiFi de convidados) pelo nome

Diagnóstico de Clientes e Grupos MAC

Ferramenta	Descrição
`omada_diagnoseClient`	Explicar por que um dispositivo (por MAC) não consegue se conectar: estado de bloqueio, grupos MAC e as listas de permitir/negar do SSID que os usam, filtro MAC do site, vínculo IP-MAC, reserva DHCP e, para chamadores ADMIN, o log de auditoria (detecta um bloqueio órfão). Somente leitura
`omada_listMacGroups`	Listar grupos MAC com suas entradas e quais SSIDs os usam como listas de permitir ou negar (modo grafo: `omada_read /profiles/mac-groups`)
`omada_setMacGroupEntry`	Adicionar um MAC a um grupo MAC, ou renomear sua entrada (requer `CONFIGURE`)
`omada_removeMacGroupEntry`	Remover um MAC de um grupo MAC (requer `CONFIGURE`)

Controle de Acesso (agendas, grupos, ACLs de gateway)

Permite que o controlador aplique uma agenda por conta própria (ex.: um toque de recolher) em vez de um loop diário de bloqueio/desbloqueio. Todas as gravações precisam de CONFIGURE.

Ferramenta	Descrição
`omada_listAccessControl`	Intervalos de tempo (janelas legíveis), grupos de IP e regras de ACL de gateway com nomes e agendas (modo grafo: `omada_read` `/profiles/time-range`, `/profiles/ip-groups`, `/network/acls/gateway`)
`omada_createTimeRange` / `omada_updateTimeRange` / `omada_deleteTimeRange`	Agendas semanais em quartos de hora, ex.: `{days:["mon","tue"], start:"14:30", end:"19:00"}`; `invertWindows` transforma horas permitidas nas bloqueadas. No máximo 7 janelas por perfil (um toque de recolher precisa de um perfil de manhã e um à noite). A exclusão é recusada enquanto uma regra o usar
`omada_createGroup` / `omada_deleteGroup`	Grupos de IP (origens/destinos de ACL) e grupos MAC (listas de permitir/negar de SSID); a exclusão é recusada para grupos integrados e grupos em uso
`omada_setDhcpReservation` / `omada_removeDhcpReservation`	IP fixo para um dispositivo (para que uma ACL possa correspondê-lo); recusa um endereço reservado para outro dispositivo
`omada_createGatewayAcl` / `omada_updateGatewayAcl` / `omada_deleteGatewayAcl` / `omada_moveGatewayAcl`	Regras de gateway (roteador) LAN-para-internet: permitir/negar uma origem (grupo de IP, rede LAN ou SSID), opcionalmente apenas durante um intervalo de tempo; cobre cabeado e Wi-Fi
`omada_setSsidMacFilter`	Ativar o filtro MAC de um SSID (grupo MAC como lista de permitir ou negar) ou desativá-lo; relata e recusa desconectar clientes conectados, a menos que `allowLockout`; `dryRun` pré-visualiza

Ferramentas de Segurança

Ferramenta	Descrição
`omada_getThreatList`	Obter lista de gerenciamento de ameaças de segurança

Ferramentas de Configuração de Rede

Ferramenta	Descrição
`omada_getInternetInfo`	Obter configuração de conexão com a internet para um site
`omada_getPortForwardingStatus`	Obter regras de encaminhamento de porta (Usuário ou UPnP)
`omada_getLanNetworkList`	Obter lista de configuração de rede LAN
`omada_getLanProfileList`	Obter lista de configuração de perfil LAN
`omada_getWlanGroupList`	Obter lista de configuração de grupo WLAN
`omada_getSsidList`	Obter lista de SSIDs para um grupo WLAN
`omada_getSsidDetail`	Obter configuração detalhada de SSID
`omada_getFirewallSetting`	Obter configuração de firewall para um site
`omada_getSiteNtpStatus`	Obter configuração e status do servidor NTP do site
`omada_setSiteNtpServers`	Substituir a lista de servidores NTP do site (requer `CONFIGURE`; `dryRun` visualiza a alteração)

Ferramentas de Rede Independentes de Fornecedor (9)

As ferramentas net_ descrevem redes da mesma forma para cada fornecedor de controlador: um modelo compartilhado, com um adaptador por fornecedor (TP-Link Omada hoje; UniFi e MikroTik estão planejados). Cada adaptador informa por recurso se é nativo, construído a partir de vários objetos ou não suportado (net_capabilities), e recusa o que não pode fazer em vez de descartar. Cada alteração é planejada primeiro: dryRun mostra as etapas, o que significam e quais dispositivos online seriam desconectados; a aplicação recusa se o controlador mudou no meio tempo, ou se dispositivos seriam desconectados sem allowLockout. Senhas de Wi-Fi nunca são obtidas ou exibidas: uma rede Wi-Fi nova ou redefinida recebe uma senha temporária aleatória, e a senha real é definida na interface web do controlador. Leituras precisam de QUERY, alterações de CONFIGURE.

Ferramenta	Descrição
`net_capabilities`	O que o controlador pode fazer, por recurso
`net_listNetworks`	Redes (VLANs): VLAN, gateway, DHCP, IPv6, protegida
`net_createNetwork` / `net_updateNetwork` / `net_deleteNetwork`	Criar ou alterar uma VLAN com seu gateway e intervalo DHCP. A rede em que o controlador está é protegida; a exclusão é recusada enquanto uma rede Wi-Fi, perfil de porta, reserva ou regra a utilizar
`net_listWifi`	Redes Wi-Fi: rede, bandas, segurança, isolamento, filtro MAC
`net_createWifi` / `net_updateWifi` / `net_deleteWifi`	Criar ou alterar um SSID em uma rede específica (bandas, WPA2/WPA3, PMF, isolamento, oculto, 802.11r, filtro MAC), ou redefinir sua senha para uma aleatória

No Omada, isolamento de rede, um tipo de rede "convidado", ativar IPv6 e modo misto WPA2/WPA3 não estão disponíveis através da API e são recusados. Regras chegam na 2.4.6, portas de switch e mDNS na 2.4.7.

Ferramentas de IA (1)

Ferramenta	Descrição
`analyzeSensors`	Analisar dados de sensores usando IA (Ollama) para detectar problemas e fornecer recomendações

Recursos MCP

URI do Recurso	Descrição
`hass://entities`	Listar todas as entidades agrupadas por domínio
`hass://entities/{entity_id}`	Obter estado de uma entidade específica
`hass://entities/{entity_id}/detailed`	Obter informações detalhadas da entidade com todos os atributos
`hass://entities/domain/{domain}`	Obter todas as entidades para um domínio
`hass://search/{query}/{limit}`	Pesquisar entidades com limite de resultados

Pré-requisitos

Node.js 20+ (testado com v20.19.6) - para métodos npm/npx
npm 10.8+ (testado com v10.8.2) - para métodos npm/npx
Docker (opcional) - para método Docker
Instância do Home Assistant com token de acesso de longa duração
Acesso de rede à sua instância do Home Assistant
(Opcional) Ollama para análise com IA

Obtendo Seu Token do Home Assistant

Faça login na sua instância do Home Assistant
Clique no seu perfil (canto inferior esquerdo)
Role para baixo até "Tokens de Acesso de Longa Duração"
Clique em "Criar Token"
Dê um nome (ex.: "Servidor MCP")
Copie o token (exibido apenas uma vez!)

Variáveis de Ambiente

Obrigatórias

Variável	Descrição	Exemplo
`HA_URL`	URL do Home Assistant	`http://homeassistant.10.0.0.19.nip.io:8123`
`HA_TOKEN`	Token de acesso de longa duração	`eyJhbGciOiJIUzI1NiIsInR5cCI...`

Opcionais - Home Assistant

Variável	Padrão	Descrição
`HA_PLUGIN_ENABLED`	`true`	Ativar plugin do Home Assistant
`HA_STRICT_SSL`	`true`	Validar certificados SSL
`HA_TIMEOUT`	`30000`	Tempo limite de solicitação da API (ms)

Opcionais - Servidor MCP

Variável	Padrão	Descrição
`MCP_SERVER_LOG_LEVEL`	`info`	Nível de log: `debug`, `info`, `warn`, `error`
`MCP_SERVER_LOG_FORMAT`	`plain`	Formato de log: `plain`, `json`, `gcp-json`
`MCP_SERVER_USE_HTTP`	`false`	Ativar modo HTTP (em vez de stdio)
`MCP_SERVER_STATEFUL`	`false`	Ativar sessões com estado no modo HTTP

Opcionais - Modo HTTP

Variável	Padrão	Descrição
`MCP_HTTP_PORT`	`3000`	Porta do servidor HTTP
`MCP_HTTP_BIND_ADDR`	`127.0.0.1`	Endereço de bind
`MCP_HTTP_PATH`	`/mcp`	Caminho do endpoint MCP
`MCP_HTTP_ENABLE_HEALTHCHECK`	`true`	Ativar endpoint de verificação de saúde
`MCP_HTTP_HEALTHCHECK_PATH`	`/health`	Caminho da verificação de saúde
`MCP_HTTP_ALLOW_CORS`	`true`	Ativar CORS
`MCP_HTTP_ALLOWED_ORIGINS`	`127.0.0.1,localhost`	Origens CORS permitidas

Opcionais - Interface de chat (superfície OpenAPI/REST)

O servidor também serve uma interface OpenAPI/REST (/openapi.json + /api/*) para UIs de chat como Open WebUI. Por padrão, expõe as 8 ferramentas clássicas do Home Assistant. Ferramentas marcadas como elegíveis para chat no código podem ser ativadas por categoria com granularidade de leitura/escrita:

Variável	Padrão	Descrição
`MCP_CHAT_TOOLS`	não definido (= 8 ferramentas HA legadas)	Fatia de categoria, ex.: `ha-core:rw,ha-history:r,omada-read:r`. Categorias: `ha-core`, `ha-history`, `ha-automations`, `omada-read`, `omada-write`. A configuração só pode restringir o que o código marca como elegível para chat; ferramentas ADMIN (`invokeAction`) nunca podem aparecer nesta interface.
`MCP_REST_ACTIONS`	não definido (= ferramenta não registrada)	Mapa JSON de ações REST pré-registradas para a ferramenta MCP `invokeAction` (ADMIN; apenas interface MCP), ex.: `{"deploy":{"url":"http://host:8425/v1/update","bearerToken":"...","cooldownMs":300000}}`. Cada ação é limitada por taxa: intervalo mínimo entre disparos = `cooldownMs` (padrão 60000; `0` desativa) — limita o raio de explosão de deploy em massa se um modelo repetir uma ação legítima

Ferramentas de chat ativadas aparecem no /openapi.json gerado como POST /api/tools/<name> e são despachadas pelos mesmos manipuladores, validação e RBAC da interface MCP.

Opcionais - Eventos SSE

Variável	Padrão	Descrição
`MCP_SSE_EVENTS_ENABLED`	`true`	Ativar eventos SSE em tempo real
`MCP_OWNER_QUESTIONS_ENABLED`	`true`	Ativar `askOwner` / `getOwnerAnswer` / `cancelOwnerQuestion` (modo HTTP com Home Assistant)
`MCP_OWNER_QUESTIONS_HA_USERS`	(qualquer usuário HA)	IDs de usuário do Home Assistant separados por vírgula permitidos a responder perguntas do proprietário (o valor `answeredBy` de uma resposta)
`MCP_SSE_EVENTS_PATH`	`/subscribe_events`	Caminho do endpoint SSE

Opcionais - Limitação de Taxa

Variável	Padrão	Descrição
`MCP_RATE_LIMIT_ENABLED`	`false`	Ativar limitação de taxa
`MCP_RATE_LIMIT_WINDOW_MS`	`60000`	Janela de limitação de taxa (ms)
`MCP_RATE_LIMIT_MAX_REQUESTS`	`100`	Máximo de solicitações por janela

Opcionais - Autenticação

Variável	Padrão	Descrição
`MCP_AUTH_METHOD`	`none`	Método de autenticação: `none` ou `bearer`
`MCP_AUTH_SECRET`	-	Segredo de assinatura JWT (mínimo 32 caracteres, obrigatório para método `bearer`)
`MCP_PERMISSIONS_CONFIG`	-	Configuração JSON para funções e permissões de usuário

Autenticação JWT

Quando MCP_AUTH_METHOD=bearer, os clientes devem fornecer um token JWT no cabeçalho Authorization:

Authorization: Bearer <jwt-token>

Gere tokens com seu MCP_AUTH_SECRET usando o algoritmo HS256. O payload JWT deve incluir:

sub (subject): Identificador do usuário para consulta de permissão
exp (opcional): Carimbo de tempo de expiração

Sistema de Permissões

O servidor usa controle de acesso baseado em funções com máscaras de permissão binárias:

Permissão	Flag	Descrição
`ADMIN`	1	Operações do sistema (reinicialização, atualizações)
`CONFIGURE`	2	Criar/modificar automações, scripts
`CONTROL`	4	Controlar dispositivos (luzes, clima, etc.)
`QUERY`	8	Ler estados de entidades, histórico, listas
`NOTIFY`	16	Enviar notificações
`AI`	32	Usar recursos de análise de IA

Funções Predefinidas:

Função	Permissões
`NONE`	Sem permissões
`READONLY`	Somente QUERY
`OPERATOR`	QUERY + CONTROL + NOTIFY
`CONTRIBUTOR`	QUERY + CONTROL + NOTIFY + CONFIGURE
`ADMIN`	Todas as seis permissões (QUERY, CONTROL, NOTIFY, CONFIGURE, AI, ADMIN)
`SUPERUSER`	Todas as permissões

Exemplo de Configuração:

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

Defina via variável de ambiente (escape as aspas para o shell):

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

Recomendado: defaultRole: "NONE" mais uma entrada users por cliente. defaultRole se aplica a todo token validamente assinado cujo sub não está listado — um padrão não-NONE concede silenciosamente acesso real a clientes não mapeados. O servidor registra um aviso na inicialização quando defaultRole concede qualquer coisa. Mapeie cada cliente (Open WebUI, n8n, agentes…) explicitamente antes de mudar uma implantação existente para NONE.

Os clientes veem apenas as ferramentas que podem usar: tools/list é filtrado pelas permissões do chamador, então um token readonly nunca recebe ferramentas de controle ou administração (as chamadas ainda são verificadas por ferramenta).

Opcionais - Provedor de IA

Variável	Padrão	Descrição
`AI_PLUGIN_ENABLED`	`true`	Ativar plugin de IA
`AI_PROVIDER`	`ollama`	Provedor de IA: `ollama`, `openai`, ou `none`
`AI_URL`	`http://localhost:11434`	URL do servidor de IA (Ollama)
`AI_MODEL`	`llama2`	Nome do modelo de IA
`AI_TIMEOUT`	`60000`	Tempo limite de solicitação de IA (ms)

Opcionais - Controlador de Rede Omada

Variável	Padrão	Descrição
`OMADA_PLUGIN_ENABLED`	`false`	Ativar plugin Omada
`OMADA_BASE_URL`	-	URL do controlador Omada (ex.: `https://10.0.0.1:8043`)
`OMADA_CLIENT_ID`	-	ID do cliente OAuth2 do controlador Omada
`OMADA_CLIENT_SECRET`	-	Segredo do cliente OAuth2 do controlador Omada
`OMADA_OMADAC_ID`	-	ID do controlador Omada
`OMADA_SITE_ID`	-	ID do site padrão para operações
`OMADA_STRICT_SSL`	`true`	Validar certificados SSL
`OMADA_TIMEOUT`	`30000`	Tempo limite de solicitação da API (ms)

Exemplos Avançados de Configuração

Com Análise 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"
      }
    }
  }
}

Desativar Recursos 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 com Configuração de Rede

Para Linux, você pode precisar adicionar 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 padrão para clientes MCP. Veja a seção Início Rápido para configuração.

Para opções de configuração detalhadas, veja docs/LOCAL_CLIENT.md.

Modo 2: Servidor HTTP

Inicie como servidor HTTP autônomo para aplicações 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 Streamable

Configure seu cliente MCP para usar:

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

Assinatura de Eventos SSE

Assine eventos em tempo 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);
});

Veja docs/SSE_API.md para documentação completa de SSE.

Modo 3: Docker Autônomo

# 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

Exemplos de Integração

Com o Claude Desktop

Após a configuração, você pode pedir ao Claude:

"Mostre-me todas as luzes da minha casa"
"Acenda as luzes da cozinha com 50% de brilho"
"Defina a temperatura da sala para 72 graus"
"Crie uma automação que desligue todas as luzes à meia-noite"
"Quais automações estão habilitadas atualmente?"
"Dispare a automação da rotina matinal"
"Pesquise entidades com 'quarto' no nome"
"Obtenha todas as entidades de clima"
"Analise meus sensores em busca de problemas" (requer Ollama)
"Verifique o histórico do meu termostato"

Com Fluxos de Trabalho n8n

O servidor pode ser integrado ao n8n para monitoramento doméstico automatizado. Fluxos de trabalho pré-construídos estão disponíveis no diretório n8n/:

ai-agent-safety-monitor - Monitoramento crítico de segurança a cada 5 minutos

Importando Fluxos de Trabalho

Método 1: Interface n8n

Abra o n8n: http://127.0.0.1:5678
Clique em Workflows → Importar do Arquivo
Selecione o arquivo JSON de n8n-files/
Ative o fluxo de trabalho

Método 2: CLI do 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

Com Aplicações Web

Use o transporte HTTP com seu cliente web compatível com MCP:

Inicie o servidor no modo HTTP
Configure o cliente para usar http://localhost:3000/mcp
Defina o transporte como Streamable HTTP (MCP 2025-03-26)
Habilite o CORS adicionando sua origem a MCP_HTTP_ALLOWED_ORIGINS

Com Proxy MCP Remoto (mcp-remote)

Conecte um cliente somente stdio (Claude Desktop, LM Studio) a um servidor MCP HTTP remoto usando mcp-remote. No Windows, inicie-o por meio de cmd /c e inclua -y para que a primeira execução nunca bloqueie no prompt de instalação do npx:

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

⚠️ Não use espaços reservados ${VAR} no valor de --header. Uma configuração como "Authorization: Bearer ${MCP_AUTH_TOKEN}" com um bloco env correspondente não funciona no Windows: cmd /c só expande %VAR% (não ${VAR}), e o mcp-remote também não o substitui. O texto literal ${MCP_AUTH_TOKEN} é enviado como token, o servidor responde 401, e o mcp-remote então cai em um fluxo OAuth com falha que aparece como "Servidor desconectado". Insira o JWT real diretamente. (No macOS/Linux você pode, em vez disso, deixar seu shell expandir a variável antes do cliente iniciar.)

Notas de Configuração de Rede

host.docker.internal - Use isso para acessar serviços na sua máquina host a partir do Docker
- Funciona no Windows e macOS por padrão
- No Linux, adicione --add-host=host.docker.internal:host-gateway aos argumentos do docker
IP Direto - Use o endereço IP da sua máquina (ex.: http://10.0.0.19:8123)
Domínios nip.io - Use DNS curinga para desenvolvimento local fácil (ex.: http://homeassistant.10.0.0.19.nip.io:8123)

Práticas Recomendadas de Segurança

Segurança de Rede

Segmentação de Rede: Execute o servidor MCP apenas na LAN privada
Redes Docker: Use redes Docker para isolamento de contêineres
VLAN: Considere VLAN para dispositivos IoT
Sem Exposição à Internet: Nunca exponha o servidor MCP diretamente à internet

Segurança de Token e Configuração

Armazene .env com segurança (contém token de acesso)
Nunca envie .env para controle de versão
Defina permissões de .env: chmod 600 .env
Use HA_STRICT_SSL=true para HTTPS em produção
Rotacione tokens de acesso periodicamente
Restrinja MCP_HTTP_ALLOWED_ORIGINS (evite curinga *)
Vincule a 127.0.0.1 para acesso somente local
Habilite limite de taxa em produção (MCP_RATE_LIMIT_ENABLED=true)

Segurança de Configuração do Cliente MCP

⚠️ Importante: Armazenar tokens diretamente em arquivos de configuração do cliente MCP (Claude Desktop, LM Studio) os expõe a qualquer pessoa com acesso ao sistema de arquivos. Considere:

Usar arquivos .env com permissões restritas para implantações Docker/locais
Definir permissões de arquivo nos arquivos de configuração (ex.: chmod 600)
Usar substituição de variáveis de ambiente, se suportada pelo seu cliente
Nunca enviar arquivos de configuração com tokens reais para controle de versão

Instruções do Servidor

O servidor fornece Instruções do Servidor MCP durante a inicialização para ajudar LLMs a entender como usar as ferramentas disponíveis de forma otimizada. As instruções são geradas dinamicamente com base nos plugins habilitados e incluem:

Consultas de Entidade: Orientação sobre paginação, inclusão de atributos e uso de ferramentas especializadas como listPersons
Controle de Dispositivos: Quando usar ferramentas de controle especializadas vs. callService genérico
Fluxos de Automação: Práticas recomendadas para criar e testar automações
Operações Omada: Requisitos de contexto do site, distinção entre cliente e dispositivo, segurança de limite de taxa
Integração Entre Plugins: Como a correlação de presença HA se relaciona com clientes de rede Omada

As instruções seguem as práticas recomendadas do MCP: concisas, acionáveis e focadas nas relações entre ferramentas, em vez de repetir descrições individuais de ferramentas.

Solução de Problemas

Claude Desktop / LM Studio Não Conectando

Verifique a localização do arquivo de configuração - Confirme se você está editando o arquivo correto
Reinicie o aplicativo - Feche e reabra após alterações na configuração
Verifique os logs - Procure mensagens de erro nos logs do aplicativo
Teste a conexão 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 Mostra "Servidor desconectado" (401)

Se /health retornar 200 mas o cliente mostrar "Servidor desconectado", o cabeçalho de autenticação está quase certamente malformado. A causa mais comum: um espaço reservado ${VAR} no valor de --header que nunca foi expandido (veja o aviso em Com Proxy MCP Remoto). Verifique se o endpoint aceita seu token diretamente:

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"}}}'

Um 200 com um resultado initialize significa que o servidor e o token estão corretos — corrija a configuração do cliente (insira o token literal). Um 401 significa que o token em si está errado.

Docker `host.docker.internal` Não Funcionando (Linux)

Adicione o gateway do host:

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

Problemas de Conexão com o Home Assistant

Verifique a URL - Tente acessar http://your-ha-url:8123/api/ no navegador
Verifique o token - Certifique-se de que é um token de acesso de longa duração válido
Acesso à rede - Verifique se o servidor MCP pode alcançar o Home Assistant
Problemas de SSL - Tente HA_STRICT_SSL=false para testes

Análise de IA Não Funcionando

Verifique se o Ollama está em execução - curl http://your-ollama-url:11434/api/tags
Verifique se o modelo está disponível - Certifique-se de que o modelo foi baixado: ollama pull llama2
Defina AI_PROVIDER - Deve ser definido como ollama (não none)

Desenvolvimento

Configuração

# 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 Disponíveis

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

Licença

MIT

Autor

Coffee Run Hobby (github.com/coffeerunhobby)

Documentação

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

MCP-HA-Connect

Documentação

MCP-HA-Connect

Principais Recursos

Funcionalidade Principal

Gerenciamento de Automações

Recursos do Sistema

Monitoramento de Rede e Segurança (TP-Link Omada)

Ferramentas Disponíveis (69 no Total)

Ferramentas do Home Assistant (38)

Ferramentas de Estado e Entidade

Ferramentas de Serviço e Controle

Ferramentas de Controle de Dispositivos

Perguntas ao Proprietário (aprovação no telefone)

Ferramentas de Automação

Ferramentas do Sistema

Ferramentas de Calendário

Ferramentas Omada de Rede (49)

Ferramentas de Site

Ferramentas de Dispositivos

Ferramentas de Clientes

Ferramentas de Limite de Taxa

Ações de Clientes e Dispositivos

Diagnóstico de Clientes e Grupos MAC

Controle de Acesso (agendas, grupos, ACLs de gateway)

Ferramentas de Segurança

Ferramentas de Configuração de Rede

Ferramentas de Rede Independentes de Fornecedor (9)

Ferramentas de IA (1)

Recursos MCP

Pré-requisitos

Obtendo Seu Token do Home Assistant

Variáveis de Ambiente

Obrigatórias

Opcionais - Home Assistant

Opcionais - Servidor MCP

Opcionais - Modo HTTP

Opcionais - Interface de chat (superfície OpenAPI/REST)

Opcionais - Eventos SSE

Opcionais - Limitação de Taxa

Opcionais - Autenticação

Autenticação JWT

Sistema de Permissões

Opcionais - Provedor de IA

Opcionais - Controlador de Rede Omada

Exemplos Avançados de Configuração

Com Análise de IA (Ollama)

Desativar Recursos de IA

Docker com Configuração de Rede

Modos de Uso

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

Modo 2: Servidor HTTP

Transporte HTTP Streamable

Assinatura de Eventos SSE

Modo 3: Docker Autônomo

Modo 4: Docker Compose

Exemplos de Integração

Com o Claude Desktop

Com Fluxos de Trabalho n8n

Importando Fluxos de Trabalho

Com Aplicações Web

Com Proxy MCP Remoto (mcp-remote)

Notas de Configuração de Rede

Práticas Recomendadas de Segurança

Segurança de Rede

Segurança de Token e Configuração

Segurança de Configuração do Cliente MCP

Instruções do Servidor

Solução de Problemas

Claude Desktop / LM Studio Não Conectando

mcp-remote Mostra "Servidor desconectado" (401)

Docker host.docker.internal Não Funcionando (Linux)

Problemas de Conexão com o Home Assistant

Análise de IA Não Funcionando

Desenvolvimento

Configuração

Scripts Disponíveis

Licença

Autor

Links

Docker `host.docker.internal` Não Funcionando (Linux)