home / mcp / home assistant light mcp server
Provides full light control and scene management for Home Assistant lights via MCP, including colors, brightness, temperature, and scene orchestration.
Configuration
View docs{
"mcpServers": {
"koneisto-homeassistant-light-mcp": {
"command": "npx",
"args": [
"-y",
"ha-mcp-server"
],
"env": {
"HA_URL": "http://your-home-assistant-ip:8123",
"HA_TOKEN": "your-long-lived-access-token"
}
}
}
}You have a dedicated MCP server that lets you control Home Assistant lights with full color support, brightness, color temperature, and scenes. It focuses on light management and scene handling, with safety-conscious design to avoid unintended changes to other types of entities. You can run it locally and connect any MCP-compatible client to manage lights and save, activate, or modify scenes at will.
You connect an MCP client to the server to view all lights, adjust their state, and manage scenes. Use commands or natural language prompts supported by your MCP client to show lights with their current color, brightness, and effects; turn lights on or off; change colors or temperatures; save the current state as a scene; activate a saved scene; and perform blackout operations. When you create or activate scenes, you have two modes: exclusive (turn off other lights not in the scene) and additive (only affect lights included in the scene). If you use IKEA Tradfri lights, expect timing considerations that this MCP handles to ensure reliable color and brightness changes.
Practical usage patterns include showing all lights, adjusting individual lights or groups, saving scenes from current states, listing saved scenes, activating scenes, updating scenes with current lighting, and applying a blackout with optional exclusions. You can perform diagnostics on lights and scenes to detect connectivity issues and conflicts, and you can fix or restore scenes from a local backup if something goes out of sync with Home Assistant.
Prerequisites: you need Node.js and npm installed on your computer.
# Option A: install the MCP server globally
npm install -g ha-mcp-server
# Option B: run via npx without a global install (recommended for quick start)
npx -y ha-mcp-serverConfigure the MCP client to connect to your Home Assistant instance by setting the Home Assistant URL and a long-lived access token. Use environment variables to keep credentials out of files.
{
"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"
}
}
}
}
```)All communication stays local between your computer and Home Assistant. Tokens are stored on your machine via environment variables, and you can revoke tokens at any time from Home Assistant. The MCP server runs locally via stdio, with no exposed network ports.
Tradfri devices may need timing-aware sequencing when switching between color modes and brightness. This MCP includes handling to insert delays and properly sequence color and brightness updates to ensure consistent results.
If a scene does not reflect the current light state, use the diagnose tool to check connectivity and scene integrity. If issues arise after a Home Assistant restart, verify the local backup file and confirm the HA URL and token are still valid in your client configuration.
Show all lights, turn on the living room light, set the kitchen light to red, save the current setup as Movie Night, activate Movie Night, update Evening Lights with current settings, and perform a blackout excluding the balcony.
Show all lights with state, brightness, colors, effects, and color modes
Control a light including on/off, brightness, color, and effects
Create a new scene from the current light states
List all saved scenes
Activate a saved scene
Update an existing scene with current lights
Delete a scene
Turn off all lights with optional exclusions
Diagnose lights and scenes and check connectivity
Repair scenes, restore from backup
Set Home Assistant URL and token