Home Assistant MCP

Home Assistant MCP

Uma integração Model Context Protocol (MCP) para controlar dispositivos Home Assistant usando assistentes de IA.

Visão Geral

Este MCP permite que assistentes de IA controlem seus dispositivos Home Assistant. Ele fornece ferramentas para:

1. Pesquisar entidades na sua instância do Home Assistant
2. Controlar dispositivos (ligar/desligar)
3. Controlar cores e brilho de luzes

Pré-requisitos

• Python 3.11 ou superior
• Instância do Home Assistant em execução e acessível via API
• Token de Acesso de Longa Duração do Home Assistant

Instalação

Instalando via Smithery

Para instalar a Integração Home Assistant para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @hpohlmann/home-assistant-mcp --client claude

Instalação Manual

1. Clone este repositório
2. Configure um ambiente Python:

cd home-assistant
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -U pip
pip install uv
uv pip install -e .

Configuração

Obter um Token de Acesso de Longa Duração do Home Assistant

1. Acesse sua instância do Home Assistant
2. Navegue até seu perfil (clique no seu nome de usuário na barra lateral)
3. Role até "Tokens de Acesso de Longa Duração"
4. Crie um novo token com um nome descritivo como "Integração MCP"
5. Copie o token (você só o verá uma vez)

Configurar no Cursor AI

Adicione a seguinte configuração à sua configuração MCP no Cursor:

{
  "mcpServers": {
    "home_assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/home-assistant-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "HOME_ASSISTANT_TOKEN": "your_home_assistant_token_here"
      },
      "inheritEnv": true
    }
  }
}

Substitua:

• /path/to/your/home-assistant pelo caminho real para este diretório
• your_home_assistant_token_here pelo seu Token de Acesso de Longa Duração do Home Assistant

Configuração da URL do Home Assistant

Por padrão, o MCP tenta conectar ao Home Assistant em http://homeassistant.local:8123.

Se o seu Home Assistant estiver em uma URL diferente, você pode modificar a variável HA_URL em app/config.py.

Uso

Após a configuração, você pode usar o Cursor AI para controlar seus dispositivos Home Assistant:

• Pesquisar dispositivos: "Encontre minhas luzes da sala de estar"
• Controlar dispositivos: "Ligue a luz da cozinha"
• Controlar cores de luzes: "Defina minhas luzes da sala de estar para vermelho"
• Ajustar brilho: "Defina minhas luzes da sala de jantar para azul com 50% de brilho"

Recursos de Controle de Luz

O MCP agora suporta recursos avançados de controle de luz:

1. Controle de Cor: Defina qualquer cor RGB para luzes compatíveis

   • Especifique cores usando valores RGB (0-255 para cada componente)
   • Exemplo: set_device_color("light.living_room", 255, 0, 0) para vermelho

2. Controle de Brilho: Ajuste o brilho da luz

   • Parâmetro de brilho opcional (0-255)
   • Pode ser combinado com alterações de cor
   • Exemplo: set_device_color("light.dining_room", 0, 0, 255, brightness=128) para azul de brilho médio

Solução de Problemas

• Se você receber erros de autenticação, verifique se seu token está correto e não expirou
• Verifique se sua instância do Home Assistant está acessível na URL configurada
• Para problemas de controle de cor:
  • Verifique se sua entidade de luz suporta controle de cor RGB
  • Verifique se a luz está ligada antes de tentar alterar as cores

Capacidades Futuras

Exposição Dinâmica de Entidades

A implementação atual requer um processo de duas etapas para controlar dispositivos:

1. Pesquisar entidades usando linguagem natural
2. Controlar a entidade usando seu entity_id específico

Uma melhoria planejada é criar uma forma mais dinâmica de expor entidades à ferramenta de controle de dispositivos, permitindo que a IA:

• Controle dispositivos diretamente por meio de comandos mais naturais (por exemplo, "desligue as luzes da cozinha")
• Armazene em cache entidades usadas com frequência para acesso mais rápido
• Suporte operações mais complexas, como ajustar brilho, temperatura ou outros atributos
• Lide com grupos de entidades e cenas de forma mais intuitiva

Isso reduziria significativamente o tempo de ação e criaria uma experiência de usuário mais fluida ao controlar dispositivos Home Assistant por meio de um assistente de IA.