@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