Skip to main content
Glama
enesjakozh
ThomasRohde

Philips Hue MCP Server

by ThomasRohde
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Philips Hue MCP Server

Python Version License: MIT MCP

A powerful Model Context Protocol (MCP) interface for controlling Philips Hue smart lighting systems. Enable AI assistants like Claude to control your lights using natural language.

Table of Contents

Related MCP server: Hass-MCP

Overview

This server leverages the Model Context Protocol (MCP) to provide a seamless integration between AI assistants like Claude and your Philips Hue lighting system. With it, you can control your smart lights using natural language, access detailed lighting information, and create advanced lighting setups through a standardized AI-friendly interface.

Features

  • Complete Light Control: Turn on/off, adjust brightness, change colors, set color temperature

  • Comprehensive Group Management: Control multiple lights together, create custom groups

  • Scene Handling: Apply existing scenes, create quick custom lighting scenes

  • Activity-Based Presets: Ready-made settings for reading, relaxation, concentration, and more

  • Special Effects: Access dynamic lighting effects like color loops

  • Natural Language Control: Specialized prompts for lighting control through conversation

  • Secure Local Integration: Connects directly to your Hue bridge on your local network

Quick Start

# Install dependencies using uv (recommended) uv sync # Test with MCP Inspector uv run mcp dev hue_server.py # Install in Claude Desktop uv run mcp install hue_server.py --name "Philips Hue"

Then in Claude, start with: "I'd like to control my Philips Hue lights. Can you show me which lights I have available?"

Setup

Prerequisites

  • Python 3.10 or higher

  • uv package manager (recommended)

  • A Philips Hue bridge on your local network

  • Philips Hue lights paired with your bridge

Installation

Using uv (recommended):

# Clone the repository git clone https://github.com/ThomasRohde/hue-mcp.git cd hue-mcp # Install dependencies and create virtual environment automatically uv sync # Activate the virtual environment (optional, uv run handles this automatically) source .venv/bin/activate # On Windows: .venv\Scripts\activate

Using pip:

# Clone the repository git clone https://github.com/ThomasRohde/hue-mcp.git cd hue-mcp # Create and activate a virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies pip install -e ".[dev]"

First Run

  1. Test the server with the MCP Inspector:

uv run mcp dev hue_server.py

  1. When prompted, press the link button on your Hue bridge to authorize the connection

  2. Your connection details will be saved in ~/.hue-mcp/config.json for future use

Using with Claude

Install in Claude Desktop

The easiest way to use this server with Claude Desktop:

# Install with default name uv run mcp install hue_server.py # Or with custom name uv run mcp install hue_server.py --name "Philips Hue Controller" # With environment variables if needed uv run mcp install hue_server.py --name "Hue" -v DEBUG=1

Manual Configuration

Alternatively, you can manually configure Claude Desktop by editing the configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

macOS:

{ "mcpServers": { "hue": { "command": "uv", "args": [ "--directory", "/Users/username/Projects/hue-mcp", "run", "hue_server.py" ] } } }

Windows:

{ "mcpServers": { "hue": { "command": "uv", "args": [ "--directory", "c:\\Users\\username\\Projects\\hue-mcp", "run", "hue_server.py" ] } } }

Replace /Users/username/Projects/hue-mcp (macOS) or c:\\Users\\username\\Projects\\hue-mcp (Windows) with the actual path to your cloned repository. The --directory flag ensures uv runs in the correct project directory and can find the dependencies defined in pyproject.toml.

After updating the configuration, restart Claude Desktop for the changes to take effect.

Test with MCP Inspector

For development and testing, use the MCP Inspector:

uv run mcp dev hue_server.py # With additional dependencies uv run mcp dev hue_server.py --with pandas # With debug logging uv run mcp dev hue_server.py --log-level debug

API Reference

Resources

Resource

Description

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

Tools

Tool

Description

get_all_lights

Get information about all lights

get_light

Get detailed information about a specific light

get_all_groups

Get information about all light groups

get_group

Get information about a specific group

get_all_scenes

Get information about all scenes

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)

turn_on_group

Turn on all lights in a group

turn_off_group

Turn off all lights in a group

set_group_brightness

Adjust group brightness (0-254)

set_group_color_rgb

Set color for all lights in a group

set_scene

Apply a scene to a group

find_light_by_name

Search for lights by name

create_group

Create a new light group

quick_scene

Apply custom settings to create a scene

refresh_lights

Update light information cache

set_color_preset

Apply a color preset to a light

set_group_color_preset

Apply a color preset to a group

alert_light

Make a light flash briefly

set_light_effect

Set dynamic effects like color loops

Prompts

Prompt

Description

control_lights

Natural language light control

create_mood

Setup mood lighting for activities

light_schedule

Learn about scheduling options

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

Command Line Arguments

The server supports the following command line arguments when run directly:

# Run with stdio transport (default, for MCP clients) python hue_server.py # Run with custom host and port (HTTP/SSE mode) python hue_server.py --sse --host 0.0.0.0 --port 8888 # Enable debug logging python hue_server.py --log-level debug # Show all available options python hue_server.py --help

Argument

Description

Default

--host

Host to bind the server to (SSE mode only)

127.0.0.1

--port

Port to run the server on (SSE mode only)

8080

--log-level

Logging level (debug, info, warning, error, critical)

info

--sse

Run server using SSE transport instead of stdio

False

Development Mode

When developing or testing:

# Use MCP dev command for automatic reloading uv run mcp dev hue_server.py --log-level debug # Or run directly with uv (stdio is default) uv run python hue_server.py --log-level debug

Troubleshooting

  • Bridge not found: If automatic discovery doesn't work, you have two options:

    1. Manually edit the BRIDGE_IP variable in the script with your bridge's IP address

    2. Manually 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

  • 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 It Works

This server connects to your Philips Hue bridge using the phue Python library and exposes functionality through the Model Context Protocol. When an AI like Claude connects:

  1. The server authenticates with your bridge using stored credentials

  2. It provides resources that describe your lighting setup

  3. It exposes tools that Claude can use to control your lights

  4. It offers prompts that help Claude understand how to interact with your lights

All communication with your Hue system happens locally within your network for security and privacy.

Contributing

We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. See the contributing guide to get started.

Project Structure

hue-mcp/ ├── hue_server.py # Main MCP server implementation ├── pyproject.toml # Project configuration and dependencies ├── README.md # This file ├── CONTRIBUTING.md # Contribution guidelines ├── CHANGELOG.md # Version history ├── LICENSE # MIT License ├── tests/ # Test suite │ ├── __init__.py │ └── test_hue_server.py └── .venv/ # Virtual environment (created during setup)

Development

# Install development dependencies uv sync # Run tests uv run pytest # Format code uv run ruff check --fix hue_server.py # Type check uv run mypy hue_server.py # Test with MCP Inspector uv run mcp dev hue_server.py --log-level debug

License

This project is available under the MIT license. See LICENSE for details.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ThomasRohde/hue-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server