io.github.Koneisto/HomeAssistant-Light-MCP
Control Home Assistant lights and scenes. Lights only by design for safety.
Open source Open in the app JSON README (API)
About
Control Home Assistant lights and scenes. Lights only by design for safety.
Details
- Kind
- MCP servers
- Topic
- IoT & hardware
- Publisher
- koneisto
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.6.1
- Last push
- 2026-01-27T19:57:41Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 03:02:01
- Updated
- 2026-08-29 03:02:01
- Origin id
io.github.Koneisto/HomeAssistant-Light-MCP
README
# 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*