Philips Hue MCP Server

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

Table of Contents

• Philips Hue MCP Server

  • Overview

  • Features

  • Quick Start

  • Setup

    • Prerequisites

    • Installation

    • First Run

  • Using with Claude

  • API Reference

    • Resources

    • Tools

    • Prompts

  • Examples

    • Controlling Single Lights

    • Working with Groups

    • Creating Scenes

  • Advanced Options

  • Troubleshooting

  • How It Works

  • Contributing

  • License

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

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:

First Run

1. Run the server:

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

3. 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:

Option 2: Test with the MCP Inspector

For development and testing:

API Reference

Resources

Tools

Prompts

Examples

Controlling Single Lights

Working with Groups

Creating Scenes

Advanced Options

Run the server with custom settings:

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.