Philips Hue MCP Server

by ThomasRohde

Integrations

  • Provides comprehensive control over Philips Hue smart lighting systems, including turning lights on/off, adjusting brightness, changing colors, managing groups, applying scenes, using activity presets, and creating lighting effects.

Philips Hue MCP Server

A powerful Model Context Protocol (MCP) interface for controlling Philips Hue smart lighting systems.

Table of Contents

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 pip install phue mcp # Run the server python hue_server.py # Install in Claude Desktop mcp install hue_server.py --name "My Hue Lights"

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.9+
  • A Philips Hue bridge on your local network
  • Philips Hue lights paired with your bridge

Installation

  1. Clone this repository or download the hue_server.py file
  2. Install the required dependencies:
pip install phue mcp

First Run

  1. Run the server:
python 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

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

API Reference

Resources

ResourceDescription
hue://lightsInformation about all lights
hue://lights/{light_id}Detailed information about a specific light
hue://groupsInformation about all light groups
hue://groups/{group_id}Information about a specific group
hue://scenesInformation about all scenes

Tools

ToolDescription
get_all_lightsGet information about all lights
get_lightGet detailed information about a specific light
get_all_groupsGet information about all light groups
get_groupGet information about a specific group
get_all_scenesGet information about all scenes
turn_on_lightTurn on a specific light
turn_off_lightTurn off a specific light
set_brightnessAdjust light brightness (0-254)
set_color_rgbSet light color using RGB values
set_color_temperatureSet light color temperature (2000-6500K)
turn_on_groupTurn on all lights in a group
turn_off_groupTurn off all lights in a group
set_group_brightnessAdjust group brightness (0-254)
set_group_color_rgbSet color for all lights in a group
set_sceneApply a scene to a group
find_light_by_nameSearch for lights by name
create_groupCreate a new light group
quick_sceneApply custom settings to create a scene
refresh_lightsUpdate light information cache
set_color_presetApply a color preset to a light
set_group_color_presetApply a color preset to a group
alert_lightMake a light flash briefly
set_light_effectSet dynamic effects like color loops

Prompts

PromptDescription
control_lightsNatural language light control
create_moodSetup mood lighting for activities
light_scheduleLearn 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

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

Contributions are welcome! Feel free to:

  • Report bugs and suggest features in the issue tracker
  • Submit pull requests with improvements
  • Share examples of how you're using this with your smart home setup

License

This project is available under the MIT license.

-
security - not tested
F
license - not found
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

A Model Context Protocol interface that enables AI assistants like Claude to control Philips Hue smart lighting systems through natural language commands.

  1. Table of Contents
    1. Overview
      1. Features
        1. Quick Start
          1. Setup
            1. Prerequisites
            2. Installation
            3. First Run
          2. Using with Claude
            1. Option 1: Install in Claude Desktop
            2. Option 2: Test with the MCP Inspector
          3. API Reference
            1. Resources
            2. Tools
            3. Prompts
          4. Examples
            1. Controlling Single Lights
            2. Working with Groups
            3. Creating Scenes
          5. Advanced Options
            1. Troubleshooting
              1. How It Works
                1. Contributing
                  1. License

                    Related MCP Servers

                    • A
                      security
                      A
                      license
                      A
                      quality
                      An enhanced Model Context Protocol server that enables AI assistants to interact with ClickUp workspaces, supporting task relationships, comments, checklists, and workspace management through natural language.
                      Last updated -
                      40
                      203
                      TypeScript
                      MIT License
                    • -
                      security
                      A
                      license
                      -
                      quality
                      A Model Context Protocol server that integrates with Home Assistant to provide smart home control capabilities through natural language, supporting devices like lights, climate systems, locks, alarms, and humidifiers.
                      Last updated -
                      Python
                      MIT License
                      • Apple
                    • -
                      security
                      A
                      license
                      -
                      quality
                      A Model Context Protocol (MCP) integration that allows AI assistants to control Home Assistant devices by searching for entities and controlling devices through natural language commands.
                      Last updated -
                      10
                      Python
                      MIT License
                      • Linux
                      • Apple
                    • -
                      security
                      A
                      license
                      -
                      quality
                      A Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.
                      Last updated -
                      15
                      Python
                      MIT License
                      • Apple
                      • Linux

                    View all related MCP servers

                    ID: qjq6xe8p1x