# homebridge-mcp

> Homebridge MCP Server — monitor and control your Homebridge smart home devices through Claude.

[![PyPI version](https://img.shields.io/pypi/v/homebridge-mcp.svg)](https://pypi.org/project/homebridge-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://python.org)

> **macOS only** — uses macOS `launchctl` to manage the Homebridge service.

**7 tools** for listing devices, checking status, searching accessories, viewing logs, restarting the service, and managing configuration — all through Claude.

## Tools

| Tool | Description |
|------|-------------|
| `homebridge_list_devices` | List all accessories with their current status |
| `homebridge_get_device` | Get details about a specific device by name or UUID |
| `homebridge_status` | Get Homebridge service status and configuration summary |
| `homebridge_logs` | View recent Homebridge logs (default: 50 lines) |
| `homebridge_restart` | Restart the Homebridge service |
| `homebridge_config` | View configuration — full config, platforms, or accessories |
| `homebridge_search_device` | Search devices by name, type, or manufacturer |

## Supported Devices

- **LG ThinQ** — refrigerators, washers, air conditioners
- **Standard HomeKit** — lights, switches, plugs, sensors
- **Temperature / Thermostat** devices
- **Contact sensors** (open/closed)
- **Motion sensors**
- Any accessory managed by Homebridge

---

## Setup

### Requirements

- **macOS** with [Homebridge](https://homebridge.io) installed and running
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager

### Install Homebridge (if needed)

Follow the official guide at [homebridge.io/getting-started](https://homebridge.io/getting-started) or install via Homebrew:

```bash
brew install homebridge
```

### Install homebridge-mcp

```bash
pip install homebridge-mcp
# or with uv:
uv add homebridge-mcp
```

### Add to Claude Code

```bash
claude mcp add homebridge -- uvx homebridge-mcp
```

Or manually in your Claude config (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "homebridge": {
      "command": "uvx",
      "args": ["homebridge-mcp"]
    }
  }
}
```

---

## How It Works

The server reads directly from Homebridge's local files — no HTTP API calls needed:

```
~/.homebridge/
├── config.json                          # Platform and plugin configuration
├── accessories/cachedAccessories        # Device state cache
└── homebridge.log                       # Service logs
```

Service management (restart, status) uses macOS `launchctl` with service label `com.homebridge.server`.

---

## Usage Examples

```
Show all my smart home devices
What is the current temperature in the living room?
Restart Homebridge
Show the last 100 lines of Homebridge logs
Search for all LG devices
```

---

## Troubleshooting

**No devices showing:**
Ensure Homebridge has run at least once and `~/.homebridge/accessories/cachedAccessories` exists.

**Restart not working:**
Confirm Homebridge is running as a launchctl service (`launchctl list | grep homebridge`). If using Docker or another method, the restart tool won't apply.

**Config shows empty:**
Check that `~/.homebridge/config.json` exists and is valid JSON.

---

## Requirements

- macOS
- [Homebridge](https://homebridge.io) installed and configured
- Python 3.10+

## License

MIT — [Hitesh Gupta](https://github.com/dev-hitesh-gupta)
