HomeMCPBridge

Integración nativa de HomeKit en macOS para asistentes de IA mediante Model Context Protocol

Documentación

HomeMCPBridge

Integración nativa de HomeKit para macOS para asistentes de IA mediante el Protocolo de Contexto de Modelos (MCP).

Controla toda tu casa inteligente con lenguaje natural — sin Homebridge, sin Home Assistant, sin servicios en la nube. Solo acceso directo a HomeKit.

¿Qué es esto?

HomeMCPBridge es una aplicación de macOS que permite a los asistentes de IA (Claude y otros que admitan MCP) controlar tus dispositivos HomeKit directamente. Pídele a tu IA que "apague las luces de la sala" o "ponga el dormitorio al 50% de brillo" y simplemente funciona.

Características

HomeKit nativo — Acceso directo al framework HomeKit de Apple, sin puentes ni trucos
Protocolo MCP — Funciona con Claude Code, Claude Desktop y cualquier IA compatible con MCP
Todos los tipos de dispositivos — Luces, interruptores, enchufes, ventiladores, cerraduras, puertas de garaje, termostatos
Control completo — Encendido/apagado, brillo, color (tono/saturación), bloquear/desbloquear, abrir/cerrar
Aplicación de barra de menú — Se ejecuta silenciosamente en segundo plano con una ventana de estado
Sistema de complementos — Amplía con Govee, Scrypted NVR y más
Vinculación de dispositivos — Vincula dispositivos HomeKit con sus contrapartes de complementos para evitar duplicados
MCPPost — Transmite eventos de sensores en tiempo real a tu sistema de IA
Capturas de cámara — Captura imágenes de cámaras HomeKit y Scrypted
Eventos de movimiento — Monitorea sensores de movimiento, timbres y sensores de contacto

Requisitos

macOS 14.0 (Sonoma) o posterior
Dispositivos compatibles con HomeKit configurados en la aplicación Apple Home
Un asistente de IA compatible con MCP (Claude Code, Claude Desktop, etc.)

Instalación

Opción 1: Descargar la versión

Descarga el último .dmg desde la página de Versiones.

Opción 2: Compilar desde el código fuente

Clona este repositorio:

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

Abre en Xcode:
```
open HomeMCPBridge.xcodeproj
```
Configura la firma para tu entorno:
- Ve al destino HomeMCPBridge > Firma y capacidades
- Selecciona tu Equipo de desarrollo en el menú desplegable
- Opcionalmente, cambia el Identificador de paquete al tuyo propio (por ejemplo, com.yourname.HomeMCPBridge)
- Estos valores se dejan intencionalmente en blanco en el repositorio para que los colaboradores puedan establecer los suyos
Compila y ejecuta (Cmd+R) — selecciona "Mi Mac (Mac Catalyst)"
Concede acceso a HomeKit cuando se te solicite

Configuración

Añade esto a tu archivo de configuración de MCP:

Para Claude Code (.mcp.json en tu proyecto o ~/.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

Una vez configurado, puedes pedirle a tu IA cosas como:

"Enumera todos mis dispositivos HomeKit"
"Enciende las luces de la cocina"
"Pon la lámpara de la sala al 50% de brillo"
"¿Cuál es la temperatura en el garaje?"
"Apaga todas las luces del patio trasero"
"Bloquea la puerta principal"
"¿Está abierta la puerta del garaje?"
"Captura una instantánea de la cámara de la puerta principal"
"¿Hay movimiento en el patio trasero?"

Herramientas MCP disponibles

Control de dispositivos

Herramienta	Descripción
`list_devices`	Enumera todos los dispositivos de HomeKit y complementos
`list_rooms`	Enumera todas las habitaciones de todos los hogares
`list_homes`	Enumera todos los hogares HomeKit configurados
`get_device_state`	Obtiene el estado actual de un dispositivo
`control_device`	Controla un dispositivo (encender, apagar, alternar, brillo, color, bloquear, desbloquear, abrir, cerrar)

Cámaras

Herramienta	Descripción
`list_cameras`	Enumera todas las cámaras HomeKit
`capture_snapshot`	Captura una imagen de la cámara (devuelve base64)

Movimiento y eventos

Herramienta	Descripción
`list_motion_sensors`	Enumera sensores de movimiento, sensores de ocupación y timbres
`get_motion_state`	Obtiene el estado actual de detección de movimiento
`subscribe_events`	Habilita el almacenamiento en búfer de eventos de movimiento y contacto
`get_pending_events`	Consulta eventos de movimiento/timbre/contacto almacenados en búfer

Scrypted NVR (requiere configuración)

Herramienta	Descripción
`scrypted_list_cameras`	Enumera todas las cámaras Scrypted con sus capacidades
`scrypted_capture_snapshot`	Captura una instantánea de la cámara Scrypted
`scrypted_get_camera_state`	Obtiene el estado de la cámara, incluida la detección de movimiento
`scrypted_set_webhook_token`	Configura el token de webhook para una cámara

Tipos de dispositivos compatibles

Luces — Encendido/apagado, brillo, color (tono/saturación)
Interruptores — Encendido/apagado
Enchufes — Encendido/apagado
Ventiladores — Encendido/apagado
Cerraduras — Bloquear/desbloquear
Puertas de garaje — Abrir/cerrar
Termostatos — Leer temperatura (control próximamente)
Sensores — Leer valores
Cámaras — Capturar instantáneas
Sensores de movimiento — Detectar movimiento/ocupación
Sensores de contacto — Abrir/cerrar puertas/ventanas

Pestañas de la aplicación

Estado

Resumen de tu configuración de casa inteligente:

Número de dispositivos Apple HomeKit
Estado de los complementos y número de dispositivos
Número de vínculos de dispositivos
Configuración de la aplicación (barra de menú, icono del dock)

Dispositivos

Explora todos los dispositivos organizados por habitación:

Toca (i) para vincular/desvincular dispositivos
Muestra la fuente del dispositivo (HomeKit, Govee, etc.)
Indica dispositivos vinculados

Complementos

Configura integraciones de terceros:

Govee — Luces y electrodomésticos inteligentes
Scrypted NVR — Cámaras de grabadora de video en red

MCPPost

Transmite eventos de sensores en tiempo real a tu IA:

Configura la URL del endpoint del webhook
Habilita/deshabilita la transmisión de eventos
Ve eventos recientes y su estado
Prueba la conectividad del endpoint

Configuración

Guía de configuración completa con:

Fragmentos de configuración de MCP
Instrucciones de configuración de complementos (Govee, Scrypted)
Configuración de MCPPost
Guía de vinculación de dispositivos

Registro

Registro de actividad completo para depuración:

Todas las llamadas a herramientas MCP
Actividad de complementos
Notificaciones de eventos
Controles de borrado y desplazamiento

Vinculación de dispositivos

Cuando tienes el mismo dispositivo tanto en HomeKit como en un complemento (como Govee), puedes vincularlos para que se traten como un solo dispositivo:

Ve a la pestaña Dispositivos
Toca el botón (i) en cualquier dispositivo
Selecciona "Vincular dispositivo..."
Elige el dispositivo correspondiente de otra fuente

Los dispositivos vinculados usan automáticamente la fuente más capaz (los complementos suelen tener más funciones que HomeKit).

MCPPost (Transmisión de eventos)

MCPPost transmite eventos de sensores en tiempo real a un endpoint HTTP personalizado, lo que permite que tu sistema de IA (como Jarvis) reciba notificaciones push.

Configuración

Abre HomeMCPBridge
Ve a la pestaña MCPPost
Ingresa la URL de tu endpoint (por ejemplo, http://localhost:8000/api/events)
Habilita la transmisión con el interruptor
Haz clic en "Probar endpoint" para verificar

Eventos compatibles

Sensores de movimiento — Movimiento detectado/despejado
Sensores de ocupación — Cambios de ocupación en la habitación
Timbres — Eventos de timbre
Sensores de contacto — Abrir/cerrar puertas/ventanas

Carga útil del 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 complementos

Complementos integrados

Complemento	Autenticación	Descripción
Apple HomeKit	Nativa (siempre habilitada)	Acceso directo a dispositivos HomeKit
Govee	Clave API	Controla luces y electrodomésticos inteligentes Govee
Scrypted NVR	Nombre de usuario/Contraseña	Accede a cámaras Scrypted y detección de movimiento

Configuración de Govee

Abre la aplicación Govee Home en tu teléfono
Ve a Configuración > Acerca de nosotros > Solicitar clave API
Espera la aprobación (generalmente en unos días)
Copia tu clave API del correo electrónico
En HomeMCPBridge, ve a Complementos > Govee e ingresa tu clave API
Habilita el complemento Govee

Configuración de Scrypted NVR

Instala y configura Scrypted en tu red
Anota la URL de tu servidor Scrypted (por ejemplo, https://mac-mini.local:10443)
Instala el complemento @scrypted/webhook en Scrypted
Para cada cámara, crea un webhook de cámara y anota el token
En HomeMCPBridge, ve a Complementos > Scrypted e ingresa las credenciales
Usa la herramienta scrypted_set_webhook_token para configurar el token de cada cámara

Guía de desarrollo de complementos

¿Quieres agregar soporte para otra plataforma de casa inteligente? Así es como crear un complemento personalizado.

Protocolo de complemento

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()
}

Registro de tu complemento

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

Privacidad

HomeMCPBridge:

Se ejecuta completamente en tu Mac
Se comunica directamente con tus dispositivos HomeKit mediante el framework de Apple
No envía datos a servidores externos (excepto MCPPost, que tú configuras)
No requiere conexión a internet para el control local de dispositivos

Solución de problemas

"No se encontraron dispositivos"

Asegúrate de tener dispositivos configurados en la aplicación Apple Home
Concede permiso de HomeKit cuando la aplicación se inicie por primera vez
Intenta reiniciar la aplicación

"Dispositivo no accesible"

Verifica que el dispositivo esté encendido y conectado a tu red
Confirma que aparezca como accesible en la aplicación Apple Home

MCP no se conecta

Asegúrate de que la aplicación esté en ejecución (revisa la barra de menú)
Verifica que la ruta en tu configuración de MCP coincida con donde instalaste la aplicación
Reinicia tu asistente de IA después de cambiar la configuración

Las instantáneas de Scrypted no funcionan

Asegúrate de que el complemento @scrypted/webhook esté instalado
Crea un webhook de cámara para cada cámara en Scrypted
Usa scrypted_set_webhook_token para configurar los tokens

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en abrir problemas o enviar solicitudes de extracción.

Licencia

Licencia MIT — consulta LICENCIA para más detalles.

Agradecimientos

Construido con el framework HomeKit de Apple
Utiliza el Protocolo de Contexto de Modelos de Anthropic