Homeassistant Light MCP

🚀 Home Assistant Light MCP

A Model Context Protocol (MCP) server for controlling Home Assistant lights and managing scenes, complementing the official MCP with detailed light control and scene management.

🚀 Quick Start

The Home Assistant Light MCP is a server designed to control Home Assistant lights and manage scenes. It offers more detailed light control and scene management features compared to the official Home Assistant MCP.

✨ Features

• Show Lights: View all lights with comprehensive details, including state, brightness, RGB colors, color temperature, color mode, supported modes, available effects, and color temperature range.
• Adjust Light: Control lights' on/off state, brightness, RGB color, color temperature, and effects.
• Create Scene: Save the current lighting as a scene in two modes: exclusive (turns off other lights when activated) and 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 the current light states.
• Delete Scene: Remove a scene.
• Blackout: Turn off all lights (with optional exclusions).

📦 Installation

You can install the Home Assistant Light MCP in two ways:

Using npm

npm install -g ha-mcp-server

Cloning and Building

git clone https://github.com/Koneisto/HomeAssistant-Light-MCP.git
cd HomeAssistant-Light-MCP
npm install
npm run build

💻 Usage Examples

Basic Usage

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"

📚 Documentation

Design Philosophy: Lights Only

This MCP is designed to control only lights, not switches or other entities. This is a safety decision:

• Switches can control critical systems such as HVAC, heaters, air conditioning, and water pumps.
• Accidental activation of these systems could be dangerous.
• Lights are generally safe, with the worst-case scenario being unexpected on/off states.

Why This MCP?

The official Home Assistant MCP has limitations in showing light colors and providing detailed state information. This MCP fills these gaps:

Configuration

Add the following configuration to your MCP client:

Claude Desktop

Edit the 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 can be used 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.

Tools Reference

Light Properties

scene_show_lights returns the following properties:

• 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. Suitable 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:

• 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 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.

Fix & Repair (scene_fix)

Four actions to repair scene problems:

IKEA Tradfri Support

IKEA Tradfri lights have issues when switching between RGB color mode and color temperature mode. This MCP provides a workaround:

• Detects Tradfri devices by manufacturer name.
• Adds a 500ms delay between mode switch and subsequent commands.
• Properly sequences color/temperature changes with brightness adjustments.

Security

• Your Data Stays Local: All communication is between your computer and your Home Assistant instance. No data is sent to external servers or third parties.
• No Tracking: The MCP does not track users.
• Token Safety: Your Home Assistant token is stored locally. Use environment variables to avoid storing tokens in files. The token is only sent to your Home Assistant instance, and you can revoke it anytime.
• Limited Access: The server can only access lights and scenes in your Home Assistant, not other entities.

📄 License

This project is licensed under the MIT License. You can use it freely, and attribution is appreciated but not required.

👨‍💻 Author

Koneisto

Built by people with questionable priorities