HomeMCPBridge

Native macOS HomeKit integration for AI assistants via the Model Context Protocol (MCP).

Control your entire smart home with natural language - no Homebridge, no Home Assistant, no cloud services. Just direct HomeKit access.

What is this?

HomeMCPBridge is a macOS app that lets AI assistants (Claude, and others that support MCP) control your HomeKit devices directly. Ask your AI to "turn off the living room lights" or "set the bedroom to 50% brightness" and it just works.

Features

• Native HomeKit - Direct access to Apple's HomeKit framework, no bridges or hacks
• MCP Protocol - Works with Claude Code, Claude Desktop, and any MCP-compatible AI
• All Device Types - Lights, switches, outlets, fans, locks, garage doors, thermostats
• Full Control - On/off, brightness, color (hue/saturation), lock/unlock, open/close
• Menu Bar App - Runs quietly in the background with a status window
• Plugin System - Extend with Govee, Scrypted NVR, and more
• Device Linking - Link HomeKit devices with plugin counterparts to avoid duplicates
• MCPPost - Broadcast real-time sensor events to your AI system
• Camera Snapshots - Capture images from HomeKit and Scrypted cameras
• Motion Events - Monitor motion sensors, doorbells, and contact sensors

Available MCP Tools

Device Control

Cameras

Motion & Events

Scrypted NVR (requires configuration)

Supported Device Types

• Lights - On/off, brightness, color (hue/saturation)
• Switches - On/off
• Outlets - On/off
• Fans - On/off
• Locks - Lock/unlock
• Garage Doors - Open/close
• Thermostats - Read temperature (control coming soon)
• Sensors - Read values
• Cameras - Capture snapshots
• Motion Sensors - Detect motion/occupancy
• Contact Sensors - Door/window open/close

App Tabs

Status

Overview of your smart home setup:

• Apple HomeKit device count
• Plugin status and device counts
• Device link count
• App settings (menu bar, dock icon)

Devices

Browse all devices organized by room:

• Tap (i) to link/unlink devices
• Shows device source (HomeKit, Govee, etc.)
• Indicates linked devices

Plugins

Configure third-party integrations:

• Govee - Smart lights and appliances
• Scrypted NVR - Network video recorder cameras

MCPPost

Broadcast real-time sensor events to your AI:

• Configure webhook endpoint URL
• Enable/disable event broadcasting
• View recent events and their status
• Test endpoint connectivity

Setup

Complete setup guide with:

• MCP configuration snippets
• Plugin setup instructions (Govee, Scrypted)
• MCPPost configuration
• Device linking guide

Log

Full activity log for debugging:

• All MCP tool calls
• Plugin activity
• Event notifications
• Clear and scroll controls

Device Linking

When you have the same device in both HomeKit and a plugin (like Govee), you can link them so they're treated as one device:

1. Go to the Devices tab
2. Tap the (i) button on any device
3. Select "Link Device..."
4. Choose the corresponding device from another source

Linked devices use the most capable source automatically (plugins usually have more features than HomeKit).

MCPPost (Event Broadcasting)

MCPPost broadcasts real-time sensor events to a custom HTTP endpoint, enabling your AI system (like Jarvis) to receive push notifications.

Configuration

1. Open HomeMCPBridge
2. Go to the MCPPost tab
3. Enter your endpoint URL (e.g., http://localhost:8000/api/events)
4. Enable broadcasting with the toggle
5. Click "Test Endpoint" to verify

Supported Events

• Motion sensors - Motion detected/cleared
• Occupancy sensors - Room occupancy changes
• Doorbells - Ring events
• Contact sensors - Door/window open/close

Event Payload

{
  "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
  }
}

Plugin System

Built-in Plugins

Govee Setup

1. Open the Govee Home app on your phone
2. Go to Settings > About Us > Apply for API Key
3. Wait for approval (usually within a few days)
4. Copy your API key from the email
5. In HomeMCPBridge, go to Plugins > Govee and enter your API key
6. Enable the Govee plugin

Scrypted NVR Setup

1. Install and configure Scrypted on your network
2. Note your Scrypted server URL (e.g., https://mac-mini.local:10443)
3. Install the @scrypted/webhook plugin in Scrypted
4. For each camera, create a Camera webhook and note the token
5. In HomeMCPBridge, go to Plugins > Scrypted and enter credentials
6. Use scrypted_set_webhook_token tool to configure each camera's token

Plugin Development Guide

Want to add support for another smart home platform? Here's how to create a custom plugin.

Plugin Protocol

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

Registering Your Plugin

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

Privacy

HomeMCPBridge:

• Runs entirely on your Mac
• Communicates directly with your HomeKit devices via Apple's framework
• Does not send any data to external servers (except MCPPost, which you configure)
• Does not require an internet connection for local device control

Requirements

• macOS 14.0 (Sonoma) or later
• HomeKit-enabled devices configured in the Apple Home app
• An MCP-compatible AI assistant (Claude Code, Claude Desktop, etc.)

Installation

Option 1: Download Release

Download the latest .dmg from the Releases page.

Option 2: Build from Source

1. Clone this repo:

   Copy

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

2. Open in Xcode:

   Copy

   open HomeMCPBridge.xcodeproj

3. Configure signing for your environment:

   • Go to the HomeMCPBridge target > Signing & Capabilities
   • Select your Development Team from the dropdown
   • Optionally change the Bundle Identifier to your own (e.g., com.yourname.HomeMCPBridge)
   • These values are intentionally left blank in the repo so contributors can set their own

4. Build and run (Cmd+R) -- select "My Mac (Mac Catalyst)"

5. Grant HomeKit access when prompted

Configuration

Add this to your MCP configuration file:

For Claude Code (.mcp.json in your project or ~/.claude/mcp.json):

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

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

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

Usage

Once configured, you can ask your AI things like:

• "List all my HomeKit devices"
• "Turn on the kitchen lights"
• "Set the living room lamp to 50% brightness"
• "What's the temperature in the garage?"
• "Turn off all the backyard lights"
• "Lock the front door"
• "Is the garage door open?"
• "Capture a snapshot from the front door camera"
• "Is there motion in the backyard?"

Troubleshooting

"No devices found"

• Make sure you have devices set up in the Apple Home app
• Grant HomeKit permission when the app first launches
• Try restarting the app

"Device not reachable"

• Check that the device is powered on and connected to your network
• Verify it shows as reachable in the Apple Home app

MCP not connecting

• Ensure the app is running (check the menu bar)
• Verify the path in your MCP config matches where you installed the app
• Restart your AI assistant after changing the config

Scrypted snapshots not working

• Ensure the @scrypted/webhook plugin is installed
• Create a Camera webhook for each camera in Scrypted
• Use scrypted_set_webhook_token to configure the tokens

License

MIT License - see LICENSE for details.