HomeMCPBridge

Integração nativa do HomeKit no macOS para assistentes de IA via Model Context Protocol

GitHub
4
Experimente este MCPPatrocinado

Documentação

HomeMCPBridge

Buy Me A Coffee

Integração nativa com HomeKit do macOS para assistentes de IA via Model Context Protocol (MCP).

Controle toda a sua casa inteligente com linguagem natural — sem Homebridge, sem Home Assistant, sem serviços em nuvem. Apenas acesso direto ao HomeKit.

O que é isto?

O HomeMCPBridge é um aplicativo macOS que permite que assistentes de IA (Claude e outros que suportam MCP) controlem seus dispositivos HomeKit diretamente. Peça à sua IA para "apagar as luzes da sala de estar" ou "definir o quarto para 50% de brilho" e ela simplesmente funciona.

Recursos

  • HomeKit nativo — Acesso direto ao framework HomeKit da Apple, sem pontes ou gambiarras
  • Protocolo MCP — Funciona com Claude Code, Claude Desktop e qualquer IA compatível com MCP
  • Todos os tipos de dispositivos — Luzes, interruptores, tomadas, ventiladores, fechaduras, portas de garagem, termostatos
  • Controle total — Ligar/desligar, brilho, cor (matiz/saturação), travar/destravar, abrir/fechar
  • Aplicativo de barra de menus — Executa silenciosamente em segundo plano com uma janela de status
  • Sistema de plugins — Estenda com Govee, Scrypted NVR e mais
  • Vinculação de dispositivos — Vincule dispositivos HomeKit com equivalentes de plugins para evitar duplicatas
  • MCPPost — Transmita eventos de sensores em tempo real para o seu sistema de IA
  • Instantâneos de câmera — Capture imagens de câmeras HomeKit e Scrypted
  • Eventos de movimento — Monitore sensores de movimento, campainhas e sensores de contato

Requisitos

  • macOS 14.0 (Sonoma) ou posterior
  • Dispositivos compatíveis com HomeKit configurados no app Casa da Apple
  • Um assistente de IA compatível com MCP (Claude Code, Claude Desktop, etc.)

Instalação

Opção 1: Baixar a versão

Baixe o .dmg mais recente na página de Releases.

Opção 2: Compilar a partir do código-fonte

  1. Clone este repositório:

    git clone https://github.com/rodaddy/HomeMCPBridge.git
cd HomeMCPBridge

  2. Abra no Xcode:

    open HomeMCPBridge.xcodeproj

  3. Configure a assinatura para o seu ambiente:

    • Vá para o alvo HomeMCPBridge > Signing & Capabilities
    • Selecione sua Development Team no menu suspenso
    • Opcionalmente, altere o Bundle Identifier para o seu próprio (por exemplo, com.yourname.HomeMCPBridge)
    • Esses valores ficam intencionalmente em branco no repositório para que os colaboradores possam definir os seus

  4. Compile e execute (Cmd+R) — selecione "My Mac (Mac Catalyst)"

  5. Conceda acesso ao HomeKit quando solicitado

Configuração

Adicione isto ao seu arquivo de configuração MCP:

Para Claude Code (.mcp.json no seu projeto ou ~/.claude/mcp.json):

{
  "mcpServers": {
    "homekit": {
      "command": "/Applications/HomeMCPBridge.app/Contents/MacOS/HomeMCPBridge",
      "args": []
    }
  }
}

Para Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "homekit": {
      "command": "/Applications/HomeMCPBridge.app/Contents/MacOS/HomeMCPBridge",
      "args": []
    }
  }
}

Uso

Depois de configurado, você pode pedir à sua IA coisas como:

  • "Liste todos os meus dispositivos HomeKit"
  • "Acenda as luzes da cozinha"
  • "Defina a luminária da sala de estar para 50% de brilho"
  • "Qual é a temperatura na garagem?"
  • "Apague todas as luzes do quintal"
  • "Tranque a porta da frente"
  • "A porta da garagem está aberta?"
  • "Capture um instantâneo da câmera da porta da frente"
  • "Há movimento no quintal?"

Ferramentas MCP Disponíveis

Controle de Dispositivos

FerramentaDescrição
list_devicesLista todos os dispositivos do HomeKit e plugins
list_roomsLista todos os cômodos de todas as casas
list_homesLista todas as casas HomeKit configuradas
get_device_stateObtém o estado atual de um dispositivo
control_deviceControla um dispositivo (ligar, desligar, alternar, brilho, cor, travar, destravar, abrir, fechar)

Câmeras

FerramentaDescrição
list_camerasLista todas as câmeras HomeKit
capture_snapshotCaptura imagem da câmera (retorna base64)

Movimento e Eventos

FerramentaDescrição
list_motion_sensorsLista sensores de movimento, sensores de ocupação, campainhas
get_motion_stateObtém o estado atual de detecção de movimento
subscribe_eventsAtiva o buffer de eventos de movimento e contato
get_pending_eventsConsulta eventos de movimento/campainha/contato em buffer

Scrypted NVR (requer configuração)

FerramentaDescrição
scrypted_list_camerasLista todas as câmeras Scrypted com capacidades
scrypted_capture_snapshotCaptura instantâneo da câmera Scrypted
scrypted_get_camera_stateObtém o estado da câmera, incluindo detecção de movimento
scrypted_set_webhook_tokenConfigura o token de webhook para uma câmera

Tipos de Dispositivos Suportados

  • Luzes — Ligar/desligar, brilho, cor (matiz/saturação)
  • Interruptores — Ligar/desligar
  • Tomadas — Ligar/desligar
  • Ventiladores — Ligar/desligar
  • Fechaduras — Travar/destravar
  • Portas de garagem — Abrir/fechar
  • Termostatos — Ler temperatura (controle em breve)
  • Sensores — Ler valores
  • Câmeras — Capturar instantâneos
  • Sensores de movimento — Detectar movimento/ocupação
  • Sensores de contato — Abrir/fechar portas e janelas

Abas do Aplicativo

Status

Visão geral da sua configuração de casa inteligente:

  • Contagem de dispositivos Apple HomeKit
  • Status dos plugins e contagem de dispositivos
  • Contagem de vínculos de dispositivos
  • Configurações do aplicativo (barra de menus, ícone no Dock)

Dispositivos

Navegue por todos os dispositivos organizados por cômodo:

  • Toque em (i) para vincular/desvincular dispositivos
  • Mostra a origem do dispositivo (HomeKit, Govee, etc.)
  • Indica dispositivos vinculados

Plugins

Configure integrações de terceiros:

  • Govee — Luzes e eletrodomésticos inteligentes
  • Scrypted NVR — Câmeras de gravador de vídeo em rede

MCPPost

Transmita eventos de sensores em tempo real para sua IA:

  • Configure a URL do endpoint do webhook
  • Ative/desative a transmissão de eventos
  • Veja eventos recentes e seu status
  • Teste a conectividade do endpoint

Configuração

Guia de configuração completo com:

  • Trechos de configuração MCP
  • Instruções de configuração de plugins (Govee, Scrypted)
  • Configuração do MCPPost
  • Guia de vinculação de dispositivos

Registro

Registro de atividades completo para depuração:

  • Todas as chamadas de ferramentas MCP
  • Atividade dos plugins
  • Notificações de eventos
  • Controles de limpar e rolar

Vinculação de Dispositivos

Quando você tem o mesmo dispositivo no HomeKit e em um plugin (como Govee), pode vinculá-los para que sejam tratados como um único dispositivo:

  1. Vá para a aba Dispositivos
  2. Toque no botão (i) em qualquer dispositivo
  3. Selecione "Vincular Dispositivo..."
  4. Escolha o dispositivo correspondente de outra origem

Dispositivos vinculados usam automaticamente a origem mais capaz (plugins geralmente têm mais recursos que o HomeKit).

MCPPost (Transmissão de Eventos)

O MCPPost transmite eventos de sensores em tempo real para um endpoint HTTP personalizado, permitindo que seu sistema de IA (como Jarvis) receba notificações push.

Configuração

  1. Abra o HomeMCPBridge
  2. Vá para a aba MCPPost
  3. Insira a URL do seu endpoint (por exemplo, http://localhost:8000/api/events)
  4. Ative a transmissão com o alternador
  5. Clique em "Testar Endpoint" para verificar

Eventos Suportados

  • Sensores de movimento — Movimento detectado/limpo
  • Sensores de ocupação — Mudanças de ocupação no cômodo
  • Campainhas — Eventos de toque
  • Sensores de contato — Abrir/fechar portas e janelas

Payload do Evento

{
  "event_id": "uuid",
  "event_type": "motion|occupancy|doorbell|contact",
  "source": "HomeKit",
  "timestamp": "2024-01-18T21:00:00Z",
  "sensor": {
    "name": "Front Door Motion",
    "id": "sensor-uuid",
    "room": "Hallway",
    "home": "Home"
  },
  "data": {
    "detected": true,
    "state": "open",
    "isOpen": true
  }
}

Sistema de Plugins

Plugins Integrados

PluginAutenticaçãoDescrição
Apple HomeKitNativa (sempre ativada)Acesso direto aos dispositivos HomeKit
GoveeChave de APIControle luzes e eletrodomésticos inteligentes Govee
Scrypted NVRNome de usuário/SenhaAcesse câmeras Scrypted e detecção de movimento

Configuração do Govee

  1. Abra o app Govee Home no seu telefone
  2. Vá para Configurações > Sobre Nós > Solicitar Chave de API
  3. Aguarde a aprovação (geralmente em alguns dias)
  4. Copie sua chave de API do e-mail
  5. No HomeMCPBridge, vá para Plugins > Govee e insira sua chave de API
  6. Ative o plugin Govee

Configuração do Scrypted NVR

  1. Instale e configure o Scrypted na sua rede
  2. Anote a URL do servidor Scrypted (por exemplo, https://mac-mini.local:10443)
  3. Instale o plugin @scrypted/webhook no Scrypted
  4. Para cada câmera, crie um webhook de Câmera e anote o token
  5. No HomeMCPBridge, vá para Plugins > Scrypted e insira as credenciais
  6. Use a ferramenta scrypted_set_webhook_token para configurar o token de cada câmera

Guia de Desenvolvimento de Plugins

Quer adicionar suporte para outra plataforma de casa inteligente? Veja como criar um plugin personalizado.

Protocolo de Plugin

protocol DevicePlugin: AnyObject {
    var identifier: String { get }
    var displayName: String { get }
    var isEnabled: Bool { get set }
    var isConfigured: Bool { get }
    var configurationFields: [PluginConfigField] { get }

    func initialize() async throws
    func shutdown() async
    func listDevices() async throws -> [UnifiedDevice]
    func getDeviceState(deviceId: String) async throws -> [String: Any]
    func controlDevice(deviceId: String, action: String, value: Any?) async throws -> ControlResult
    func configure(with credentials: [String: String]) async throws
    func clearCredentials()
}

Registrando Seu Plugin

func application(_ application: UIApplication, didFinishLaunchingWithOptions...) {
    PluginManager.shared.register(MyPlatformPlugin())
}

Privacidade

O HomeMCPBridge:

  • Executa inteiramente no seu Mac
  • Comunica-se diretamente com seus dispositivos HomeKit via framework da Apple
  • Não envia nenhum dado para servidores externos (exceto MCPPost, que você configura)
  • Não requer conexão com a internet para controle local de dispositivos

Solução de Problemas

"Nenhum dispositivo encontrado"

  • Certifique-se de ter dispositivos configurados no app Casa da Apple
  • Conceda permissão ao HomeKit quando o aplicativo iniciar pela primeira vez
  • Tente reiniciar o aplicativo

"Dispositivo inacessível"

  • Verifique se o dispositivo está ligado e conectado à sua rede
  • Confirme se ele aparece como acessível no app Casa da Apple

MCP não conectando

  • Certifique-se de que o aplicativo esteja em execução (verifique a barra de menus)
  • Verifique se o caminho na sua configuração MCP corresponde ao local onde você instalou o aplicativo
  • Reinicie seu assistente de IA após alterar a configuração

Instantâneos do Scrypted não funcionando

  • Certifique-se de que o plugin @scrypted/webhook esteja instalado
  • Crie um webhook de Câmera para cada câmera no Scrypted
  • Use scrypted_set_webhook_token para configurar os tokens

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou enviar PRs.

Licença

Licença MIT — consulte LICENSE para detalhes.

Agradecimentos