@mp-consulting/homebridge-mcp-server

MCP (Model Context Protocol) server for Homebridge — control your smart home accessories, manage plugins, edit configuration, and monitor your Homebridge server from AI assistants like Claude.

Features

• Accessories — List, inspect, and control all your Homebridge accessories (lights, switches, thermostats, sensors, etc.)
• Server Management — Check status, restart Homebridge, view pairing info, manage cached accessories
• Configuration — Read and update your config.json
• Plugins — List installed plugins, search npm, view config schemas and changelogs
• System Info — CPU, memory, OS, and network details of the host machine

Prerequisites

• Homebridge with homebridge-config-ui-x installed (provides the REST API)
• Node.js 18+

Installation

npm install -g @mp-consulting/homebridge-mcp-server

Configuration

The server requires three environment variables:

Variable	Description	Example
HOMEBRIDGE_URL	URL of your Homebridge UI	http://192.168.1.100:8581
HOMEBRIDGE_USERNAME	Homebridge UI login username	admin
HOMEBRIDGE_PASSWORD	Homebridge UI login password	admin

Usage

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "homebridge": {
      "command": "homebridge-mcp-server",
      "env": {
        "HOMEBRIDGE_URL": "http://192.168.1.100:8581",
        "HOMEBRIDGE_USERNAME": "admin",
        "HOMEBRIDGE_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add homebridge -- homebridge-mcp-server

Then set the environment variables in your shell or .env file.

MCP Inspector (for testing)

HOMEBRIDGE_URL=http://192.168.1.100:8581 \
HOMEBRIDGE_USERNAME=admin \
HOMEBRIDGE_PASSWORD=your-password \
npx @modelcontextprotocol/inspector homebridge-mcp-server

Available Tools

Accessories

Tool	Description
list_accessories	List all accessories with current state. Supports filtering by room, type, name, manufacturer, and excludeManufacturer
get_accessory	Get detailed info for a specific accessory
set_accessory	Control an accessory (on/off, brightness, temperature, etc.)
get_accessory_layout	Get the room layout from the Homebridge UI

Server

Tool	Description
get_homebridge_status	Check if Homebridge is running
get_server_status	Get server version, uptime, Node.js version, OS details, and instance ID
restart_homebridge	Restart the Homebridge service
get_pairing_info	Get HomeKit pairing code / QR info
get_cached_accessories	List cached accessories
remove_cached_accessory	Remove a specific cached accessory
reset_cached_accessories	Reset all cached accessories

Configuration

Tool	Description
get_config	Read the current config.json
update_config	Update config.json (full replacement)

Plugins

Tool	Description
list_plugins	List installed plugins
search_plugins	Search npm for Homebridge plugins
lookup_plugin	Get details about a specific plugin
get_plugin_versions	Get available versions for a plugin
get_plugin_config_schema	Get the configuration schema for a plugin
get_plugin_changelog	Get the changelog for a plugin

System

Tool	Description
get_system_info	Get host system information (CPU, memory, OS)

Example Prompts

Once configured, you can ask Claude things like:

• "List all my smart home accessories and their current status"
• "Turn off the living room lights"
• "Set the bedroom thermostat to 21 degrees"
• "What plugins are installed on my Homebridge?"
• "Show me the Homebridge config"
• "Is Homebridge running? What version?"
• "Search for a Homebridge plugin for Philips Hue"

Development

git clone https://github.com/mp-consulting/homebridge-mcp-server.git
cd homebridge-mcp-server
npm install
npm run build

npm run dev          # Run with auto-reload (tsx)
npm test             # Run tests
npm run test:watch   # Run tests in watch mode

License

MIT