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