Home Assistant MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Busca fuzzy de entidades + busca profunda de configurações em milhares de entidades
Criar e editar automações, scripts, cenas e helpers em YAML
Editor de dashboard: criar cards, layouts e views
Consultas de histórico + estatísticas com saída pronta para gráficos
Dashboard de energia, snapshots de câmera, rastreamento de automações

Demo ao vivo

Como fica na prática

ha-mcp.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "ha-mcp",
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "ha-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "ha-mcp"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add ha-mcp -- uvx ha-mcp

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Home Assistant MCP

Controlar dispositivos sem precisar memorizar entity IDs

👤 Qualquer pessoa com uma instalação populada do Home Assistant ⏱ ~5 min beginner

Quando usar: Você sabe o que quer ("deixe a cozinha em 30%") mas não sabe o entity_id exato.

Pré-requisitos

Token de Acesso de Longa Duração do Home Assistant — Perfil → Segurança → Criar Token; salve como variável de ambiente HA_TOKEN
HA_URL configurado — Defina HA_URL=http://homeassistant.local:8123 (ou sua URL)

Fluxo

Encontrar a entidade

Use ha-mcp. Find entities matching 'kitchen light'. Show entity_id, area, and current state.✓ Copiado

→ 1–3 entidades candidatas com estado atual
Aplicar a mudança

Set kitchen ceiling lights to 30% brightness, warm white.✓ Copiado

→ Chamada de serviço bem-sucedida; estado confirmado

Resultado: Dispositivos controlados por intenção, não por memorização.

Armadilhas

Várias entidades correspondem — a errada é acionada — Sempre confirme a lista de entity_ids antes de ação em massa; use filtros por área

Criar uma automação complexa a partir de uma descrição em linguagem natural

👤 Usuários do HA que evitam YAML ⏱ ~15 min intermediate

Quando usar: Você quer «se eu sair de casa depois do pôr do sol e a comedoura do gato estiver vazia, me envie uma notificação» — sem escrever YAML.

Fluxo

Descrever a intenção

Use ha-mcp. List my person tracker, sun, and cat feeder entities so we can wire an automation.✓ Copiado

→ Entidades relevantes com esquema de estado
Gerar o YAML

Create automation 'cat-feeder-sundown-alert' with that logic. Don't deploy yet — show me the YAML.✓ Copiado

→ YAML de automação do HA válido no chat
Implantar + rastrear

Deploy it. Then trigger it manually and show the trace so I can verify the conditions fired.✓ Copiado

→ Automação na UI; trace mostra os ramos esperados

Resultado: Automação funcionando sem editar /config/automations.yaml à mão.

Armadilhas

Automação implantada mas nunca dispara — erro de digitação no nome da entidade — Use a tool trace; verifique se o entity_id está exatamente correto

Investigar um pico de energia usando histórico + estatísticas

👤 Donos de casas inteligentes com Dashboard de Energia do HA ⏱ ~25 min intermediate

Quando usar: Sua conta de luz aumentou e você quer saber o que mudou.

Fluxo

Buscar os totais

Use ha-mcp. Compare total kWh per circuit for last 30 days vs the prior 30. Flag deltas >20%.✓ Copiado

→ Tabela por circuito com deltas destacados
Investigar o pior

For the worst-offending circuit, plot hourly usage for the last 7 days and identify the new pattern.✓ Copiado

→ Perfil horário + observação verbal da anomalia
Encontrar o dispositivo culpado

Which entity on that circuit changed behavior? Cross-reference automations that touch it.✓ Copiado

→ Dispositivo específico + automação identificados

Resultado: Resposta concreta como «o carregador do VE executou uma nova programação», não suspeita vaga.

Armadilhas

Estatísticas são tão boas quanto sua cobertura de sensores — Reconheça lacunas; sugira onde adicionar monitoramento

Configurar um 'modo férias' que controla luzes, fechaduras, persianas e notificações

👤 Prestes a viajar ⏱ ~30 min intermediate

Quando usar: Você sai em uma hora e quer simulação de presença + comportamento no modo ausente.

Fluxo

Inventariar entidades afetadas

Use ha-mcp. List lights in living areas, all door locks, all blinds. Note which are HA-controllable.✓ Copiado

→ Lista categorizada de entidades com flag de controlabilidade
Construir o script

Create a script 'vacation_mode_on' that arms locks, randomizes evening lights 18:30–22:30, sets blinds to 50%, and pauses cleaning automations.✓ Copiado

→ Script no HA; execução manual bem-sucedida
Adicionar um gatilho

Bind it to an input_boolean 'vacation_mode' so I can toggle from the dashboard.✓ Copiado

→ Toggle no dashboard; ativá-lo executa o script

Resultado: Modo férias com um clique; você sai com o dashboard armado.

Armadilhas

Trancando fechaduras automaticamente com pessoas dentro — Adicione uma verificação de presença de pessoas; nunca tranque quando alguém estiver em casa

Combinações

Combine com outros MCPs para 10× de alavancagem

ha-mcp + filesystem

Fazer backup de automations.yaml + scripts.yaml no git

Export all automations and scripts via ha-mcp, write to ./ha-config/, commit.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
search_entities	query: str, area?, domain?	Primeiro passo em quase todo fluxo — encontrar o entity_id	1 chamada à API do HA
call_service	domain, service, target, data	Aplicar qualquer mudança em dispositivo ou cena	1 chamada de API
create_automation	yaml_or_object	Criar automações programaticamente	1 chamada de API
get_history	entity_id, start, end	Buscar histórico de estados para análise	1 chamada de API
get_statistics	statistic_id, period (5min\|hour\|day\|month)	Dados agregados de longo prazo (energia, clima)	1 chamada de API
trace_automation	automation_id, run_id?	Depurar por que uma automação disparou ou não	1 chamada de API

Custo e limites

O que custa rodar

Cota de API: Sem cota rígida — a API REST é local
Tokens por chamada: Variável; o registro de entidades pode ser enorme se você não filtrar
Monetário: Gratuito (código aberto)
Dica: Sempre use search_entities com filtros — dumps completos do registro são caros em tokens

Segurança

Permissões, segredos, alcance

Escopos mínimos: Long-Lived Access Token (escopo completo do HA)

Armazenamento de credenciais: Variável de ambiente HA_TOKEN

Saída de dados: Apenas para a URL da sua instância HA — mantenha na rede local idealmente

Nunca conceda: Token do HA a qualquer LLM na nuvem em que não confia — isso controla acesso físico (fechaduras, garagem)

Tokens de longa duração não rotacionam automaticamente — rotacione manualmente se suspeitar de vazamento
Teste automações e fechaduras de forma que não o deixe trancado do lado de fora (tenha um backup)

Solução de problemas

Erros comuns e correções

Não consegue conectar ao HA

Verifique se HA_URL é acessível de onde o MCP roda; verifique trusted_proxies se estiver atrás de um proxy reverso

Verificar: curl $HA_URL/api/ -H 'Authorization: Bearer $HA_TOKEN'

401 Unauthorized

Token expirado ou revogado — gere um novo token de longa duração no perfil

Chamada de serviço retorna 400

Incompatibilidade na assinatura do serviço — use o painel de ferramentas do desenvolvedor para verificar o esquema e tente novamente

Automação implantada mas não dispara

Use trace_automation para ver qual condição falhou; comum: erro de digitação no entity_id ou condição de sol com fuso horário errado

Alternativas

Home Assistant MCP vs. outros

Alternativa	Quando usar	Troca
Assistentes de voz nativos do Home Assistant (Piper/Whisper)	Você quer controle por voz sem um LLM na nuvem no caminho	Menos flexibilidade em linguagem natural; mais configuração
ha-mcp-server (legado/forks)	Seu fork tem recursos que este não tem	Superfície menor; este tem 87 tools e manutenção ativa

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills