Hue Lights MCP server for AI agents

The Philips Hue MCP Server provides an interface for controlling your Philips Hue lighting system through AI assistants like Claude. Using the Model Context Protocol (MCP), it enables natural language control of your smart lights, allowing you to adjust brightness, change colors, manage groups, and create custom scenes.

Installation

Prerequisites

Python 3.9+
A Philips Hue bridge on your local network
Philips Hue lights paired with your bridge

Getting Started

Install the required dependencies:

pip install phue mcp

Download the server file:
- Clone the repository or download the hue_server.py file directly
Run the server for the first time:

python hue_server.py

When prompted, press the link button on your Hue bridge to authorize the connection
- Your connection details will be saved in ~/.hue-mcp/config.json for future use

Using with Claude

Option 1: Install in Claude Desktop

If you have Claude Desktop installed:

mcp install hue_server.py --name "Philips Hue Controller"

Option 2: Test with the MCP Inspector

For development and testing:

mcp dev hue_server.py

Once connected, you can start by asking Claude: "I'd like to control my Philips Hue lights. Can you show me which lights I have available?"

Available Resources and Tools

Resources

hue://lights - Information about all lights
hue://lights/{light_id} - Detailed information about a specific light
hue://groups - Information about all light groups
hue://groups/{group_id} - Information about a specific group
hue://scenes - Information about all scenes

Main Control Tools

get_all_lights - Get information about all lights
get_light - Get detailed information about a specific light
turn_on_light - Turn on a specific light
turn_off_light - Turn off a specific light
set_brightness - Adjust light brightness (0-254)
set_color_rgb - Set light color using RGB values
set_color_temperature - Set light color temperature (2000-6500K)
get_all_groups - Get information about all light groups
turn_on_group - Turn on all lights in a group
turn_off_group - Turn off all lights in a group
set_scene - Apply a scene to a group

Usage Examples

Controlling Single Lights

# Turn on a light
turn_on_light(1)

# Set a light to 50% brightness
set_brightness(1, 127)

# Change a light color to purple
set_color_rgb(1, 128, 0, 128)

# Set reading mode
set_color_preset(1, "reading")

Working with Groups

# Turn off all lights in living room (group 2)
turn_off_group(2)

# Create a new group
create_group("Bedroom", [3, 4, 5])

# Set all kitchen lights to energizing mode
set_group_color_preset(3, "energize")

Creating Scenes

# Apply an existing scene
set_scene(2, "abc123")  # Group 2, scene ID abc123

# Create a quick relaxing scene for the living room
quick_scene("Evening Relaxation", group_id=2, rgb=[255, 147, 41], brightness=120)

Advanced Options

Run the server with custom settings:

python hue_server.py --host 0.0.0.0 --port 8888 --log-level debug

Troubleshooting

Bridge Not Found

If automatic discovery doesn't work:

Manually edit the BRIDGE_IP variable in the script with your bridge's IP address
Or create a config file:

# Create the config directory
mkdir -p ~/.hue-mcp

# Create a config.json file with your bridge IP
echo '{"bridge_ip": "192.168.1.x"}' > ~/.hue-mcp/config.json

Replace "192.168.1.x" with your actual Hue bridge IP address.

Other Common Issues

Connection issues: Delete ~/.hue-mcp/config.json and restart the server to re-authenticate
Light control not working: Use refresh_lights tool to update the light information cache
Groups or scenes not showing up: Restart the bridge and server to sync all data

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "hue-lights" '{"command":"python","args":["hue_server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "hue-lights": {
            "command": "python",
            "args": [
                "hue_server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "hue-lights": {
            "command": "python",
            "args": [
                "hue_server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect