Home Assistant Light

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.

How to use

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.

How to install

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-server

Additional setup and configuration

Configure 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"
      }
    }
  }
}
```)

Security and local data

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.

Notes on usage with IKEA Tradfri

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.

Troubleshooting and tips

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.

Examples of common actions

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.

Available tools

scene_show_lights

Show all lights with state, brightness, colors, effects, and color modes

scene_adjust_light

Control a light including on/off, brightness, color, and effects

scene_create

Create a new scene from the current light states

scene_list

List all saved scenes

scene_activate

Activate a saved scene

scene_update

Update an existing scene with current lights

scene_delete

Delete a scene

scene_blackout

Turn off all lights with optional exclusions

scene_diagnose

Diagnose lights and scenes and check connectivity

scene_fix

Repair scenes, restore from backup

scene_configure

Set Home Assistant URL and token