Servidor MCP Home Assistant | Awesome MCP Servers

Hass-MCP

Um servidor Model Context Protocol (MCP) para integração do Home Assistant com Claude e outros LLMs.

Visão Geral

O Hass-MCP permite que assistentes de IA como o Claude interajam diretamente com sua instância do Home Assistant, permitindo que eles:

Consultem o estado de dispositivos e sensores
Controlem luzes, interruptores e outras entidades
Obtenham resumos da sua casa inteligente
Solucionem problemas de automações e entidades
Busquem por entidades específicas
Criem conversas guiadas para tarefas comuns

Capturas de Tela

Recursos

Gerenciamento de Entidades: Obtenha estados, controle dispositivos e busque entidades
Resumos por Domínio: Obtenha informações de alto nível sobre tipos de entidades
Suporte a Automações: Liste e controle automações
Conversas Guiadas: Use prompts para tarefas comuns, como criar automações
Busca Inteligente: Encontre entidades por nome, tipo ou estado
Edição de Dashboard ao Vivo: Leia e edite dashboards do Lovelace (cards e visualizações) pela API WebSocket do Home Assistant — as alterações aparecem instantaneamente nos navegadores abertos, com backups automáticos e pré-visualização de teste
Eficiência de Tokens: Respostas JSON enxutas para minimizar o uso de tokens

Instalação

Pré-requisitos

Instância do Home Assistant com Token de Acesso de Longa Duração
Um dos seguintes:
- Docker (recomendado)
- Python 3.13+ e uv

Configuração com Claude Desktop

Instalação via Docker (Recomendada)

Baixe a imagem Docker:
```
docker pull voska/hass-mcp:latest
```
Adicione o servidor MCP ao Claude Desktop:

a. Abra o Claude Desktop e vá para Configurações b. Navegue até Desenvolvedor > Editar Config c. Adicione a seguinte configuração ao seu arquivo claude_desktop_config.json:
```
{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}
```
d. Substitua YOUR_LONG_LIVED_TOKEN pelo seu token de acesso de longa duração real do Home Assistant e. Atualize o HA_URL:
- Se estiver executando o Home Assistant na mesma máquina: use http://host.docker.internal:8123 (Docker Desktop no Mac/Windows)
- Se estiver executando o Home Assistant em outra máquina: use o IP ou hostname real
f. Salve o arquivo e reinicie o Claude Desktop
A ferramenta "Hass-MCP" deve agora aparecer no menu de ferramentas do seu Claude Desktop

Nota: Se você estiver executando o Home Assistant em Docker na mesma máquina, talvez seja necessário adicionar --network host aos argumentos do Docker para que o contêiner acesse o Home Assistant. Alternativamente, use o endereço IP da sua máquina em vez de host.docker.internal.

uv/uvx

Instale o uv no seu sistema.
Adicione o servidor MCP ao Claude Desktop:

a. Abra o Claude Desktop e vá para Configurações b. Navegue até Desenvolvedor > Editar Config c. Adicione a seguinte configuração ao seu arquivo claude_desktop_config.json:
```
{
  "mcpServers": {
    "hass-mcp": {
      "command": "uvx",
      "args": ["hass-mcp"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}
```
d. Substitua YOUR_LONG_LIVED_TOKEN pelo seu token de acesso de longa duração real do Home Assistant e. Atualize o HA_URL:
- Se estiver executando o Home Assistant na mesma máquina: use http://host.docker.internal:8123 (Docker Desktop no Mac/Windows)
- Se estiver executando o Home Assistant em outra máquina: use o IP ou hostname real
f. Salve o arquivo e reinicie o Claude Desktop
A ferramenta "Hass-MCP" deve agora aparecer no menu de ferramentas do seu Claude Desktop

Outros Clientes MCP

Cursor

Vá para Configurações do Cursor > MCP > Adicionar Novo Servidor MCP
Preencha o formulário:
- Nome: Hass-MCP
- Tipo: command
- Comando:
```
docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
```
- Substitua YOUR_LONG_LIVED_TOKEN pelo seu token real do Home Assistant
- Atualize o HA_URL para corresponder ao endereço da sua instância do Home Assistant
Clique em "Adicionar" para salvar

Claude Code (CLI)

Para usar com o Claude Code CLI, você pode adicionar o servidor MCP diretamente usando o comando mcp add:

Usando Docker (recomendado):

claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

Substitua YOUR_LONG_LIVED_TOKEN pelo seu token real do Home Assistant e atualize o HA_URL para corresponder ao endereço da sua instância do Home Assistant.

Transporte HTTP (Streamable)

Para implantações que não podem usar stdio — executando atrás de um gateway MCP, hospedando no Smithery, compartilhando um servidor entre vários clientes, ou conectando-se a partir de ferramentas baseadas em rede como LibreChat ou OpenWebUI — o Hass-MCP suporta o transporte HTTP streamable do MCP. O servidor executa em modo sem estado (sem Mcp-Session-Id, respostas JSON), adequado para hosts com escala horizontal.

[!CAUTION] O modo HTTP expõe controle total do Home Assistant pela rede. Qualquer pessoa que possa alcançar a porta pode chamar qualquer ferramenta — desligar luzes, destrancar portas, acionar automações, reiniciar o HA. A especificação MCP ainda não inclui uma camada de autenticação embutida neste servidor. Até que isso aconteça, você deve colocá-lo atrás de um dos seguintes:

Um proxy reverso (nginx, Caddy, Traefik) fazendo validação de basic-auth ou bearer-token

Uma VPN ou rede de confiança zero (Tailscale, WireGuard, Cloudflare Access)

Apenas vinculação a localhost (o padrão — altere --host somente se você souber o que está fazendo)

Não exponha :8000 à internet aberta sem autenticação.

Executando localmente

Usando uvx:

HA_URL=http://homeassistant.local:8123 \
HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
uvx hass-mcp --http --port 8000

O servidor vincula 127.0.0.1 por padrão. Substitua com --host 0.0.0.0 somente quando você também tiver configurado autenticação na frente dele.

Executando em Docker

docker run --rm -p 8000:8000 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000

--host 0.0.0.0 é necessário dentro do Docker para que a porta seja alcançável através da ponte. Vincule a publicação (-p) a 127.0.0.1:8000:8000 se você quiser que seja alcançável apenas a partir do host, ou coloque um proxy reverso na frente.

Endpoint

O endpoint MCP está em /mcp. Aponte seu cliente para http://<host>:<port>/mcp.

Smithery / PaaS

O servidor honra a variável de ambiente PORT (convenção do Smithery) além de MCP_PORT. A implantação no Smithery requer o modo --http e lê PORT automaticamente.

CA Personalizada / Privada

Se sua instância do Home Assistant serve um certificado assinado pela sua própria CA (step-ca, smallstep, OpenSSL de homelab), o hass-mcp pode verificá-lo sem desabilitar TLS:

Localmente: instale a raiz da CA no armazenamento de confiança do seu sistema operacional (Keychain do macOS, Cert Store do Windows, ou update-ca-certificates no Linux). O hass-mcp o detecta automaticamente via truststore.
Em Docker (ou qualquer runtime em sandbox): monte o arquivo da CA e aponte SSL_CERT_FILE para ele.

docker run --rm \
  -v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
  -e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
  -e HA_URL=https://homeassistant.example.internal:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest

SSL_CERT_FILE sempre tem precedência sobre o armazenamento do sistema operacional quando definido. verify=False não é suportado intencionalmente — use HA_URL=http://... se você realmente quiser tráfego LAN local não criptografado.

Exemplos de Uso

Aqui estão alguns exemplos de prompts que você pode usar com o Claude depois que o Hass-MCP estiver configurado:

"Qual é o estado atual das luzes da minha sala de estar?"
"Desligue todas as luzes da cozinha"
"Qual é a temperatura no quarto principal?"
"Liste tudo no quarto de hóspedes"
"Liste todos os meus sensores que contêm dados de temperatura"
"Dê-me um resumo das minhas entidades de clima"
"Crie uma automação que acende as luzes ao pôr do sol"
"Ajude-me a solucionar por que minha automação do sensor de movimento do quarto não está funcionando"
"Busque por entidades relacionadas à minha sala de estar"
"Mostre-me as últimas 50 linhas de ERRO do log do Home Assistant"
"O que falhou na integração mqtt hoje?"
"Mostre-me o uso de energia por dia no último mês"
"O que aconteceu com o sensor da porta da frente na terça-feira passada?"

Ferramentas Disponíveis

O Hass-MCP fornece várias ferramentas para interagir com o Home Assistant:

get_version: Obtenha a versão do Home Assistant
get_entity: Obtenha o estado de uma entidade específica com filtragem opcional de campos
entity_action: Execute ações em entidades (ligar, desligar, alternar)
list_entities: Obtenha uma lista de entidades com filtragem opcional por domínio e busca
search_entities_tool: Busque por entidades que correspondam a uma consulta
domain_summary_tool: Obtenha um resumo das entidades de um domínio
list_automations: Obtenha uma lista de todas as automações
call_service_tool: Chame qualquer serviço do Home Assistant
restart_ha: Reinicie o Home Assistant
get_history: Obtenha o histórico de estados de uma entidade (últimas N horas)
get_history_range: Obtenha o histórico de mudanças de estado de uma entidade em um intervalo de data/hora explícito (start_time / end_time, ISO-8601)
get_statistics: Obtenha estatísticas agregadas de longo prazo (média / mín / máx por intervalo) para uma entidade nas últimas N horas — funciona para dados mais antigos que a janela de retenção de curto prazo do gravador
get_statistics_range: O mesmo, mas para um intervalo de data/hora explícito — útil para consultas de tendências mensais / anuais
get_error_log: Obtenha o log de erros do Home Assistant, com filtros opcionais level / integration / search_term / lines aplicados no lado do servidor para que logs ruidosos não estourem o contexto do Claude
get_entities_by_area: Liste entidades em uma área / cômodo específico

Edição de Dashboard (Lovelace)

Leia e edite dashboards ao vivo pela API WebSocket do Home Assistant. Salvar envia a alteração para todos os navegadores abertos instantaneamente — sem reinicialização.

list_dashboards: Liste dashboards (o padrão mais quaisquer dashboards de usuário), cada um com seu url_path e mode (storage / yaml)
get_dashboard_config: Obtenha a configuração completa de um dashboard
set_dashboard_config: Substitua a configuração completa de um dashboard (baixo nível)
add_card / update_card / remove_card / move_card: Edite cards dentro de uma visualização (a visualização é selecionada por índice, ou por seu path / title)
list_view_sections: Liste as seções de uma visualização do tipo "sections"
add_view / remove_view / update_view: Edite as visualizações de um dashboard
list_dashboard_backups / restore_dashboard: Liste e reverta para os backups automáticos pré-salvamento

Visualizações de seções: O tipo de visualização moderno do Home Assistant (type: sections) armazena seus cards dentro de seções em vez de uma única lista de nível superior. Para essas visualizações, chame list_view_sections e passe o argumento section (índice, título ou cabeçalho) para as ferramentas de card. Edições de card em uma visualização de seções sem um section são rejeitadas com a lista de seções disponíveis — em vez de salvar silenciosamente um card onde ele nunca seria renderizado.

Toda ferramenta de edição aceita dry_run=true para pré-visualizar a configuração resultante e um resumo das alterações sem salvar.

Notas importantes:

Token de administrador necessário. Salvar a configuração do Lovelace exige que o token de longa duração pertença a um usuário administrador.
Somente modo de armazenamento. Apenas dashboards gerenciados pela interface ("storage") podem ser editados. Dashboards em modo YAML são detectados e rejeitados com uma mensagem clara — edite seus arquivos YAML diretamente.
Gravações de configuração completa. O Home Assistant não tem API de edição parcial; cada alteração é uma leitura-modificação-gravação de todo o dashboard. As ferramentas de card/visualização de alto nível lidam com isso para você.
Backups automáticos. Antes de cada gravação, a configuração atual é salva em HASS_MCP_BACKUP_DIR (padrão ~/.hass-mcp/dashboard-backups/). Ao executar em Docker, monte um volume neste caminho ou os backups serão perdidos quando o contêiner for recriado.

Prompts para Conversas Guiadas

O Hass-MCP inclui vários prompts para conversas guiadas:

create_automation: Guia para criar automações do Home Assistant com base no tipo de gatilho
debug_automation: Ajuda para solucionar automações que não estão funcionando
troubleshoot_entity: Diagnosticar problemas com entidades
routine_optimizer: Analisar padrões de uso e sugerir rotinas otimizadas com base no comportamento real
automation_health_check: Revisar todas as automações, encontrar conflitos, redundâncias ou oportunidades de melhoria
entity_naming_consistency: Auditar nomes de entidades e sugerir melhorias de padronização
dashboard_layout_generator: Criar dashboards otimizados com base nas preferências do usuário e padrões de uso

Recursos Disponíveis

O Hass-MCP fornece os seguintes endpoints de recursos:

hass://entities/{entity_id}: Obtenha o estado de uma entidade específica
hass://entities/{entity_id}/detailed: Obtenha informações detalhadas sobre uma entidade com todos os atributos
hass://entities: Liste todas as entidades do Home Assistant agrupadas por domínio
hass://entities/domain/{domain}: Obtenha uma lista de entidades para um domínio específico
hass://search/{query}/{limit}: Busque por entidades que correspondam a uma consulta com limite de resultados personalizado

Desenvolvimento

Executando Testes

uv run pytest tests/

Licença

Licença MIT

Home Assistant

Documentação