ha-mcp

Um servidor Model Context Protocol (MCP) que fornece a assistentes de IA acesso ao Home Assistant, permitindo controle de casa inteligente e gerenciamento de automação.

GitHub

Experimente este MCPPatrocinado

Documentação

ha-mcp

Um servidor Model Context Protocol (MCP) que fornece a assistentes de IA acesso ao Home Assistant, permitindo controle de casa inteligente e gerenciamento de automação.

Recursos

41 Ferramentas Especializadas: Consultas de entidades, CRUD de automações, gerenciamento de auxiliares, scripts, cenas, dispositivos, áreas, rótulos, andares, zonas, pessoas, tags, rastros, blueprints, atualizações, tarefas, calendários, câmeras, painéis, log do sistema e muito mais
Arquitetura Híbrida: WebSocket para a maioria das operações, API REST para CRUD de automações/scripts/cenas
CRUD Completo: Criar, ler, atualizar, excluir automações/scripts/cenas/auxiliares
Acesso Profundo ao Sistema: Consultar registros, analisar dependências, acessar livro de registro, validar configuração
Saída Flexível: Formatos em linguagem natural (otimizado para LLM) e JSON
Controle de Acesso: Modo somente leitura, lista de permissões/negações, controle refinado em nível de ação
Reconexão Automática: Reconexão automática com backoff exponencial
Confirmação Pós-Mutação: Polling automático de estado após criar/atualizar/excluir confirma alterações

vs. Outros Servidores MCP para Home Assistant

Existem duas alternativas: a integração oficial HA MCP (componente Core integrado, ~15 ferramentas de intenção) e a comunitária homeassistant-ai/ha-mcp (Python/FastMCP, 88 ferramentas).

Escolha ha-mcp se você precisar de:

Gerenciamento completo do ciclo de vida de automações, scripts, cenas e auxiliares (criar, editar, excluir)
Patch JSON RFC 6902 e semântico para automações e painéis sem sobrescrever arquivos inteiros
Gerenciamento de auxiliares em 41 tipos, incluindo fluxos de entrada de configuração em várias etapas e subtipos de modelo
Diagnóstico profundo (análise de raio de explosão, gráficos de dependência, pesquisa de referência entre configurações)
Diff de estado pós-mutação (Smart Wait confirma entity: off -> on inline)
Uso eficiente de contexto LLM: 42 ferramentas consolidadas consomem ~3.500 tokens de espaço de esquema, em comparação com mais de 15.000 tokens para 88 ferramentas separadas
Binário estático único com zero dependências de runtime e baixo uso de memória

Escolha a integração oficial se você precisar de controle básico de dispositivos sem configuração externa, ou depender estritamente das configurações de exposição do Assist Voice.

Escolha o ha-mcp comunitário se você precisar de execução dentro do HA via HACS ou Add-on, filas de política de aprovação com intervenção humana, ou filtros de ocultação de entidades.

Consulte docs/feature-comparison.md para uma matriz detalhada de comparação entre os três.

Instalação

A partir do Binário

Baixe a versão mais recente na página de Releases.

# Linux/macOS
tar -xzf ha-mcp_linux_amd64.tar.gz
chmod +x ha-mcp
sudo mv ha-mcp /usr/local/bin/

# Windows: extract ha-mcp_windows_amd64.zip and add to PATH

A partir do Código Fonte

Requer Go 1.27 ou posterior.

git clone https://github.com/zorak1103/ha-mcp.git
cd ha-mcp
task install-hooks  # install git pre-commit hook (auto-fixes gofmt on every commit)
task lint:install   # install golangci-lint built with your local Go toolchain
go build -o ha-mcp ./cmd/ha-mcp

Pacotes Linux

Pacotes RPM e DEB estão disponíveis nas versões:

sudo dpkg -i ha-mcp_amd64.deb   # Debian/Ubuntu
sudo rpm -i ha-mcp_amd64.rpm    # RHEL/Fedora

Docker

docker pull zorak1103/ha-mcp:latest
docker run -d --name ha-mcp -p 8080:8080 \
  -e HA_URL=http://homeassistant.local:8123 \
  zorak1103/ha-mcp:latest

Consulte docs/configuration.md para opções do Docker, HTTPS/WSS, suporte a proxy e todas as variáveis de ambiente.

Início Rápido

Obtenha um token de acesso de longa duração na página de perfil do seu Home Assistant.
Inicie o servidor:

# With flags
ha-mcp --ha-url http://homeassistant.local:8123 --ha-token your-token

# Or initialize config files first
ha-mcp init   # creates config.yaml and .env
ha-mcp        # start with config file

Conecte seu cliente de IA. Exemplo para Claude Desktop:

{
  "mcpServers": {
    "homeassistant": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": { "Authorization": "Bearer your-ha-access-token" }
    }
  }
}

Consulte docs/configuration.md para configurações de Cline, opencode e outros clientes.

Comandos Disponíveis

Comando	Descrição
`ha-mcp`	Inicia o servidor MCP
`ha-mcp init`	Cria config.yaml e .env no diretório atual
`ha-mcp config`	Exibe a configuração efetiva (tokens mascarados)
`ha-mcp --help`	Mostra ajuda e flags disponíveis

Ferramentas Disponíveis

42 ferramentas organizadas por domínio. Referência completa em docs/tools.md.

Sete tópicos de orientação também estão disponíveis como recursos MCP sob URIs skill://ha-mcp/<slug> (seleção-de-formato, padrões-de-automação, resiliência-de-modelo, seleção-de-auxiliar, segurança-de-painel, renomeação-de-entidade, fluxo-de-depuração).

Categoria	Contagem	Destaques
Entidade	5	`query_entities` (histórico/estatísticas/saúde), `get_state`, `analyze_entity`
Registro	10	`get_registry`, `manage_area/label/floor/zone/person/tag/entity/device`
Automação	1	`manage_automation` (CRUD, alternar, cobertura, JSON Patch + patch semântico)
Auxiliares	2	`manage_helper` (41 tipos), `helper_action`
Scripts e Cenas	2	`manage_script`, `manage_scene` (CRUD + executar/ativar + JSON Patch + patch semântico)
Análise	4	`analyze_entity`, `get_entity_dependencies`, `analyze_target`, `find_references`
Serviços	2	`call_service`, `list_services` (chamadas com tipo de resposta via `return_response`)
Histórico/Livro de Registro	2	`query_entities` modos, `get_logbook` (entradas + correlação)
Painéis/Mídia	4	`manage_dashboard` (JSON Patch + patch semântico), `browse_media`, `manage_camera`, `sign_media_path`
Calendários e Tarefas	2	`manage_calendar`, `manage_todo`
Sistema/Admin	7	`get_system_info`, `validate_config`, `manage_update`, `manage_blueprint`
Logs	1	`manage_system_log` (listar entradas WARN/ERROR, limpar buffer circular)
Estatísticas	1	`manage_statistics` (listar, validar, limpar estatísticas de longo prazo do gravador)
HACS	1	`manage_hacs` (listar, baixar, instalar, repositórios personalizados)
Orientação	1	`get_skill` (ação=list para descobrir habilidades, ação=read para buscar conteúdo)

Controle de Acesso

ha-mcp fornece modo somente leitura, lista de permissões e lista de negações com filtragem no nível de ferramenta e ação:

# config.yaml - read-only monitoring
server:
  read_only: true

# Or block specific operations
server:
  tool_filter:
    blacklist:
      - "call_service"
      - "manage_*:delete"

Consulte docs/access-control.md para padrões glob, filtragem por categoria (*:write) e cenários de exemplo.

Arquitetura

AI Client → HTTP/JSON-RPC → ha-mcp MCP Server
                                    │
               ┌────────────────────┴────────────────────┐
               │ WebSocket (primary)                      │ REST API
               │ - State queries, service calls           │ - Automation CRUD
               │ - Helper CRUD, Registry access           │ - Script/Scene CRUD
               └────────────────────┬────────────────────┘
                                    │
                             Home Assistant

Consulte docs/architecture.md para estrutura do projeto, comandos de build e configuração de testes de integração.

Solução de Problemas

Consulte docs/troubleshooting.md para problemas de conexão WebSocket, modo de depuração e soluções para erros comuns.

Desenvolvimento

Um contêiner de desenvolvimento pré-configurado está disponível; consulte .devcontainer/README.md.

Pré-requisitos: Go 1.27+, golangci-lint v2, Docker (opcional)

go build -o ha-mcp ./cmd/ha-mcp    # Build
go test ./...                       # Unit tests
golangci-lint run --timeout=5m ./...  # Lint

Se golangci-lint entrar em pânico com "file requires newer Go version", seu binário instalado localmente foi compilado com uma toolchain Go mais antiga do que a do PATH. Execute task lint:install para recompilá-lo com sua toolchain atual.

Consulte docs/architecture.md para configuração de testes de integração e docs/integration-tests.md para a documentação completa da suíte de testes.

Contribuindo

Consulte CONTRIBUTING.md para o fluxo de trabalho completo (comandos de tarefas, requisito de TDD, configuração de testes de integração, regras de linter e a lista de verificação de documentação para novas ferramentas). Leia também o Código de Conduta.

Licença

Licença GPL-3.0 - consulte LICENSE para detalhes.

Agradecimentos

Especificação Model Context Protocol
API WebSocket do Home Assistant
coder/websocket - Biblioteca WebSocket pura em Go