Hue Lights

🚀 Philips Hue MCP Server

The Philips Hue MCP Server is a powerful tool for controlling and managing Philips Hue smart bulbs, enabling seamless interaction with AI through natural language processing.

🚀 Quick Start

The Philips Hue MCP (Model Context Protocol) Server is a tool designed to control and manage Philips Hue smart bulbs. It communicates with the Philips Hue Bridge via the MCP protocol, allowing artificial intelligence (such as Claude) to control lights through natural language processing.

✨ Features

• Resource Provision: Define resources such as devices, lights, groups, and scenes.
• Tool Exposure: Offer various operation tools, including turning lights on/off, adjusting brightness, changing colors, and setting scene modes.
• Prompt Interaction: Include built - in prompts to help AI understand how to interact with the lighting system.

💻 Usage Examples

Basic Usage

Controlling a Single Light

# Turn on a light
turn_on_light(1)

# Adjust brightness to 50%
set_brightness(1, 127)

# Set the color to purple
set_color_rgb(1, 128, 0, 128)

# Apply the reading mode
set_color_preset(1, "reading")

Controlling a Group

# Turn off the living room light group (Group ID = 2)
turn_off_group(2)

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

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

Creating a Scene Mode

# Apply a configured scene mode
set_scene(2, "abc123")  # Group ID = 2, Scene Mode ID = abc123

# Create a quick relaxation scene mode
quick_scene("Night Relaxation", group_id=2, rgb=[255, 147, 41], brightness=120)

🔧 Technical Details

Advanced Usage

Customize the server configuration through command - line parameters:

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

• --host: Specify the IP address to which the server binds (default is the local IP).
• --port: Specify the port on which the server listens (default is 8090).
• --log-level: Set the log level (debug, info, warning, etc.).

Troubleshooting

1. Bridge Not Found:
   • Manually edit the configuration file and set the BRIDGE_IP variable to the IP address of your Hue Bridge.
   • Create a blank configuration file and specify the bridge IP:

     mkdir -p ~/.hue-mcp
     echo '{"bridge_ip": "192.168.1.x"}' > ~/.hue-mcp/config.json
     

     Replace 192.168.1.x with the actual IP address of your bridge.
2. Connection Issues:
   • Delete the configuration file and restart the server for re - authentication:

     rm ~/.hue-mcp/config.json
     

3. Light Control Failure:
   • Use the refresh_lights tool to update the light information cache.
4. Groups or Scene Modes Not Displayed:
   • Restart the bridge and the server to synchronize data.

How It Works

1. Authentication and Connection: Establish a secure connection with the bridge using the Philips Hue protocol.
2. Resource Provision: Define resources such as lights, groups, and scene modes for AI to call.
3. Tool Interaction: Expose control tools through the MCP protocol, enabling AI to perform lighting operations.
4. Natural Language Processing: Use built - in prompts to help AI understand user intentions and convert them into specific operation instructions.

🤝 Contribution

We welcome your issues and suggestions!

• Repository: https://github.com/your-repository
• Submit Issues or Pull Requests to improve the functionality.

📄 License

This project is licensed under the MIT License:

Copyright (c) Year, Author Name
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

It allows both personal and commercial use. When distributing derivative works, the copyright notice, license information, and disclaimer must be retained.