Home Assistant Light MCP Server

Home Assistant Light MCP

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:

Installation

npm install -g ha-mcp-server

Or clone and build:

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)

{
  "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

npm install -g ha-mcp-server

{
  "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