openhue-mcp-server

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

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

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.

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

This server exposes the following capabilities through MCP:

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

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

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

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

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?"

Lists all lights or gets details for specific lights

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

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
}

Lists all rooms or gets specific room details

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

Controls all lights in a room

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

Lists available scenes

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

Activates a specific scene

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

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

npm run build

npm start

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

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

MIT License

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request