📌Overview

Purpose: To facilitate control of Philips Hue lights via the MCP server, allowing interactions through Claude and other LLM interfaces using the OpenHue CLI.

Overview: The OpenHue MCP Server provides a user-friendly way to manage Philips Hue lighting systems through natural language commands, enhancing the smart home experience. It integrates seamlessly with Claude for easy control of lighting environments and includes a straightforward setup process.

Key Features:

Lights Control: Enables users to list lights, turn them on/off, adjust brightness, set colors, and control color temperature, allowing for personalized lighting settings.
Room Control: Lets users manage multiple lights in a room collectively, offering functionalities to list rooms, control room-wide settings, and streamline lighting adjustments.
Scene Management: Provides capabilities to list and activate predefined scenes, facilitating quick adjustments to lighting moods tailored for different activities or atmospheres.

OpenHue MCP Server

An MCP server that enables control of Philips Hue lights through Claude and other LLM interfaces using the OpenHue CLI.

Prerequisites

Node.js (v16 or higher)
Docker
Claude for Desktop (optional, for testing)

Bridge Setup

Before using the server, set up the OpenHue CLI with your Hue Bridge:

Run the setup command:

# On Linux/macOS:
docker run -v "${HOME}/.openhue:/.openhue" --rm --name=openhue -it openhue/cli setup

# On Windows (PowerShell):
docker run -v "${env:USERPROFILE}\.openhue:/.openhue" --rm --name=openhue -it openhue/cli setup

Follow the on-screen instructions:
- The CLI will search for your Hue Bridge.
- Press the link button on your Hue Bridge when prompted.
- Wait for confirmation that the setup is complete.
Verify the setup by listing your lights:

# On Linux/macOS:
docker run -v "${HOME}/.openhue:/.openhue" --rm --name=openhue -it openhue/cli get lights

# On Windows (PowerShell):
docker run -v "${env:USERPROFILE}\.openhue:/.openhue" --rm --name=openhue -it openhue/cli get lights

If your lights are listed, the setup is complete and you can use the MCP server.

Installation

Clone the repository:

git clone <your-repo-url>
cd claude-mcp-openhue

Install dependencies:

npm install

Build the project:

npm run build

Run the server:

npm start

Features

This server exposes the following capabilities through MCP:

Lights Control

List all lights or get specific light details
Turn lights on/off
Adjust brightness
Set colors
Control color temperature

Room Control

List all rooms or get room details
Control all lights in a room together
Set room-wide brightness and colors

Scene Management

List available scenes
Activate scenes with different modes
Filter scenes by room

Usage with Claude Desktop

Open your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the server configuration:

{
  "mcpServers": {
    "hue": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"]
    }
  }
}

Restart Claude Desktop.
Look for the hammer icon to verify the server is connected.

Example Commands

You can ask Claude natural language questions like:

"What lights do I have in the living room?"
"Turn on all the lights in the kitchen"
"Set the bedroom lights to 50% brightness"
"Change the office lights to blue"
"Activate the 'Relaxing' scene"
"What scenes are available in the den?"

Available Tools

get-lights

Lists all lights or gets details for specific lights

{
  lightId?: string;  // Optional light ID or name
  room?: string;     // Optional room name filter
}

control-light

Controls individual lights

{
  target: string;    // Light ID or name
  action: "on" | "off";
  brightness?: number; // 0-100
  color?: string;     // Color name
  temperature?: number; // 153-500 Mirek
}

get-rooms

Lists all rooms or gets specific room details

{
  roomId?: string;  // Optional room ID or name
}

control-room

Controls all lights in a room

{
  target: string;    // Room ID or name
  action: "on" | "off";
  brightness?: number;
  color?: string;
  temperature?: number;
}

get-scenes

Lists available scenes

{
  room?: string;    // Optional room name filter
}

activate-scene

Activates a specific scene

{
  name: string;     // Scene name or ID
  room?: string;    // Optional room name
  mode?: "active" | "dynamic" | "static";
}

Development

Project Structure

.
├── src/
│   └── index.ts    # Main server implementation
├── build/          # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Running

npm start

Troubleshooting

Server Not Connecting

Check that Docker is running.
Verify OpenHue configuration exists.
Check Claude Desktop logs.
Try running OpenHue CLI directly.

Command Failures

Check OpenHue CLI permissions.
Verify light/room/scene names.
Check Docker container logs.
Verify Hue Bridge connectivity.

License

MIT License

Contributing

Fork the repository.
Create your feature branch.
Commit your changes.
Push to the branch.
Create a new Pull Request.

openhue-mcp-server