# Home Assistant Light MCP
[](https://www.npmjs.com/package/ha-mcp-server)
[](https://github.com/Koneisto/HomeAssistant-Light-MCP/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
A Model Context Protocol (MCP) server for controlling Home Assistant lights and managing scenes. Complements the official Home Assistant MCP by providing detailed light control with colors and scene management.
> **Like this project?** Give it a ⭐ on GitHub and help others discover it!
## Design Philosophy: Lights Only
This MCP **intentionally controls only lights** - not switches, not other entities. This is a deliberate safety decision:
- **Switches can control critical systems** - HVAC, heaters, air conditioning, water pumps
- **Accidental activation could be dangerous** - turning on a heater while away, disabling AC in summer
- **Lights are safe** - worst case is lights turn on/off unexpectedly
If you need to control switches or other entities, use the official Home Assistant MCP or automations with appropriate safeguards.
## Features
- **Show Lights** - View all lights with full details:
- State, brightness, RGB colors, color temperature
- Color mode and supported modes
- Available effects (colorloop, etc.)
- Color temperature range (min/max Kelvin)
- **Adjust Light** - Control lights (on/off, brightness, RGB color, color temperature, effects)
- **Create Scene** - Save current lighting as a scene with two modes:
- `exclusive` - Turns off other lights when activated
- `additive` - Only affects lights in the scene
- **List Scenes** - View all saved scenes
- **Activate Scene** - Activate a saved scene (with IKEA Tradfri support)
- **Update Scene** - Update an existing scene with current light states
- **Delete Scene** - Remove a scene
- **Blackout** - Turn off all lights (with optional exclusions)
## Why This MCP?
The official Home Assistant MCP is limited - it can't show light colors or provide detailed state information. This MCP fills that gap:
| Feature | Official HA MCP | This MCP |
|---------|-----------------|----------|
| Show light colors | No | Yes |
| Show brightness | Limited | Full detail |
| Show color modes | No | Yes |
| Show effects | No | Yes |
| Set RGB colors | No | Yes |
| Color temperature | No | Yes |
| Set effects | No | Yes |
| Create scenes | No | Yes |
| IKEA Tradfri fixes | No | Yes |
## Installation
```bash
npm install -g ha-mcp-server
```
Or clone and build:
```bash
git clone https://github.com/Koneisto/HomeAssistant-Light-MCP.git
cd HomeAssistant-Light-MCP
npm install
npm run build
```
## Configuration
Add to your MCP client configuration:
### Claude Desktop
Edit config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Option 1: Using npx (recommended, no global install needed)**
```json
{
"mcpServers": {
"ha-light-scenes": {
"command": "npx",
"args": ["-y", "ha-mcp-server"],
"env": {
"HA_URL": "http://your-home-assistant-ip:8123",
"HA_TOKEN": "your-long-lived-access-token"
}
}
}
}
```
**Option 2: Global install**
```bash
npm install -g ha-mcp-server
```
```json
{
"mcpServers": {
"ha-light-scenes": {
"command": "ha-mcp-server",
"env": {
"HA_URL": "http://your-home-assistant-ip:8123",
"HA_TOKEN": "your-long-lived-access-token"
}
}
}
}
```
### Other MCP Clients
The same configuration structure works with any MCP-compatible client.
### Get your Home Assistant token
1. Go to Home Assistant → Profile (bottom left)
2. Scroll to "Long-Lived Access Tokens"
3. Click "Create Token"
4. Copy the token
## Usage Examples
### Show lights
> "Show me all the lights"
> "What lights are on?"
### Control lights
> "Turn on living room light"
> "Set bedroom to 50% brightness"
> "Make the kitchen light red"
> "Set studio lights to warm white"
> "Start colorloop on the hallway light"
### Create a scene
> "Save this as Movie Night"
### Activate a scene
> "Activate Movie Night"
### Update a scene
> "Update Evening Lights with current settings"
### Blackout
> "Turn off all lights"
> "Turn off all lights except the balcony"
## Tools Reference
| Tool | Description |
|------|-------------|
| `scene_show_lights` | Show all lights with state, brightness, colors, effects, color modes |
| `scene_adjust_light` | Control a light (on/off, brightness, color, effects) |
| `scene_create` | Create a new scene from current light states |
| `scene_list` | List all scenes |
| `scene_activate` | Activate a scene |
| `scene_update` | Update existing scene with current lights |
| `scene_delete` | Delete a scene |
| `scene_blackout` | Turn off all lights (supports exclusions) |
| `scene_diagnose` | Diagnose lights and scenes, check connectivity |
| `scene_fix` | Fix scene problems, restore from backup |
| `scene_configure` | Set Home Assistant URL and token |
### Light Properties
`scene_show_lights` returns:
- `state` - on/off
- `brightness` / `brightness_pct` - 0-255 / 0-100%
- `rgb_color` - [R, G, B] values
- `color_temp_kelvin` - Color temperature
- `color_mode` - Current mode (xy, color_temp, rgb, hs)
- `supported_color_modes` - What the light supports
- `effect` - Active effect (if any)
- `effect_list` - Available effects
- `color_temp_range` - Min/max Kelvin (if supported)
## Scene Modes
- **Exclusive**: Turns off all lights not in the scene. Good for room-specific scenes.
- **Additive**: Only affects lights in the scene. Good for accent lighting.
## Local Backup & Multi-Instance Support
This MCP maintains a local backup of scenes you create:
- **Automatic backup**: Scenes are saved to `~/.config/ha-mcp-server/scenes-backup.json`
- **Multi-instance aware**: Detects when another MCP instance (or HA UI) modifies scenes
- **Smart conflict resolution**: Merges changes from multiple sources
- **Restore capability**: Can restore scenes if Home Assistant loses them
### Diagnostics (`scene_diagnose`)
Analyzes your lights and scenes to identify problems:
- Tests light connectivity and response times
- Detects connection types (Zigbee, WiFi, Bluetooth)
- Finds scenes with null values or missing lights
- Compares Home Assistant state with local backup
- Reports new lights not yet in exclusive scenes
Example: *"Run diagnostics on my lights"*
### Fix & Repair (`scene_fix`)
Four actions to repair scene problems:
| Action | Description |
|--------|-------------|
| `fix_all` | Auto-fix all scenes: remove null values, add missing lights to exclusive scenes |
| `fix_scene` | Fix a specific scene by name |
| `test_scene` | Activate a scene and report what went wrong |
| `restore_from_backup` | Restore scenes from local backup if Home Assistant lost them |
Example: *"Fix all my scenes"* or *"Restore Evening Lights from backup"*
## IKEA Tradfri Support
IKEA Tradfri lights have a known issue when switching between RGB color mode and color temperature (Kelvin) mode. The bulbs need time to process the mode change before accepting brightness or color values.
**Note:** Home Assistant's native scenes don't work reliably with Tradfri lights due to these timing issues. This MCP provides a workaround by managing scenes independently with proper delays.
This MCP automatically handles Tradfri lights by:
- Detecting Tradfri devices by manufacturer name
- Adding a 500ms delay between mode switch and subsequent commands
- Properly sequencing color/temperature changes with brightness adjustments
Without these fixes, Tradfri lights often ignore commands or produce incorrect colors when switching modes.
## Security
### Your Data Stays Local
- All communication happens directly between your computer and your Home Assistant instance
- No data is sent to external servers or third parties
- The MCP server runs locally on your machine via stdio (no open network ports)
### No Tracking
- We don't care enough to track you
### Token Safety
- Your Home Assistant token is stored only on your local machine
- Use environment variables to avoid storing tokens in files
- The token is only sent to your own Home Assistant instance
- You can revoke the token anytime from Home Assistant settings
### What This Server Can Access
- Only lights and scenes in your Home Assistant
- Cannot access other Home Assistant entities (sensors, locks, cameras, etc.)
- Cannot make changes outside of light control and scene management
## Contributing
Found a bug or have an idea? [Open an issue](https://github.com/Koneisto/HomeAssistant-Light-MCP/issues) or submit a pull request!
## License
MIT - Use freely, attribution appreciated but not required.
## Author
[Koneisto](https://github.com/Koneisto)
---
*Built by people with questionable priorities*
