OpenHue MCP server

The OpenHue MCP Server enables control of Philips Hue lights through Claude and other LLM interfaces using the OpenHue CLI. This server bridges the gap between your language model assistants and your smart lighting system, allowing for natural language control of your Hue ecosystem.

Prerequisites

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

Bridge Setup

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

1. 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

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

3. 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 you see your lights listed, the setup is complete and you're ready to use the MCP server.

Installation

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. 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

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration:

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

3. Restart Claude Desktop

4. Look for the hammer icon to verify the server is connected

Example Commands

Once connected, 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", // 0-100
  "color?": "string",     // Color name
  "temperature?": "number" // 153-500 Mirek
}

get-scenes

Lists available scenes

{
  "roomId?": "string"  // Optional room ID or name to filter scenes
}

activate-scene

Activates a specific scene

{
  "sceneId": "string",   // Scene ID or name
  "mode?": "string"      // Optional activation mode
}

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "hue" '{"command":"node","args":["/absolute/path/to/build/index.js"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect