Hue MCP Server

🌈 Hue MCP Server

A modern Model Context Protocol (MCP) server that enables AI assistants to control Philips Hue smart lighting systems with natural language.

✨ Features

🎨 Natural Language Control - "Turn the living room lights to stormy dusk"
🔍 Smart Light Search - "Find all color bulbs in the bedroom"
🏠 Smart Room & Zone Management - Control entire rooms and zones with single commands
🌟 Atmospheric Variation - Individual light variations for realistic scenes
🎭 Scene Activation - Browse and activate predefined lighting scenes
🧠 AI-Optimized Tools - Enhanced responses with quick actions and suggestions
💬 Chatbot UX Optimized - Smart response sizing and context management
⚡ Intelligent Caching - 95% reduction in API calls with graceful fallbacks
🔧 Modern Setup Wizard - Beautiful React-based configuration experience
🔒 Secure & Local - All communication stays on your local network
🛠️ Developer Friendly - TypeScript-first with comprehensive testing

🚀 Quick Start

Prerequisites

Node.js 18+
Philips Hue Bridge (v2) on your local network
Claude Desktop or compatible MCP client

1. Installation

git clone https://github.com/your-username/hue-mcp.git
cd hue-mcp
npm install

2. Setup Your Hue Bridge

Option A: Web Setup (Recommended)

npm run setup:web

This launches a beautiful setup wizard at http://localhost:3000 that will:

Auto-discover your Hue bridge
Guide you through authentication
Test your connection
Generate Claude Desktop configuration

Option B: CLI Setup

npm run setup

3. Add to Claude Desktop

Copy the generated configuration to your Claude Desktop config file:

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

{
  "mcpServers": {
    "hue-lights": {
      "command": "node",
      "args": ["/path/to/hue-mcp/dist/index.js"],
      "env": {
        "HUE_BRIDGE_IP": "192.168.1.100",
        "HUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Start Using

Restart Claude Desktop and try these commands:

"Turn on the living room lights"
"Set bedroom to warm white at 30%"
"Activate the energize scene"
"Show me all available lights"
"Turn everything off"

📚 Documentation

Installation Guide - Detailed setup instructions
MCP Tools Reference - Complete tool documentation
Natural Language Examples - Command examples and patterns
Troubleshooting - Common issues and solutions
Development Guide - Contributing and extending
API Reference - Technical API documentation

💡 Optimal Usage Patterns

For Chatbot Efficiency

🔍 Discovery Queries

❌ Avoid: "List all lights" (potentially large response)
✅ Better: "Find lights that are on" (filtered, relevant)
✅ Best: "Quick status" (minimal context summary)

🏠 Room Controls

❌ Avoid: Multiple individual light commands
✅ Better: "Turn off all bedroom lights" (single room command)
✅ Best: "Set bedroom to relaxing mood" (scene activation)

📊 Status Checking

❌ Avoid: Detailed system overview every time
✅ Better: "Minimal status" (compact summary)
✅ Best: Context-aware - detailed first time, minimal after

Response Size Guidelines

First interaction: Use standard detail level for orientation
Ongoing conversation: Use compact to preserve context window
Troubleshooting: Use verbose for comprehensive information
Quick checks: Use minimal for status updates

🛠️ Available Commands

Command	Description
`npm run setup:web`	Launch interactive web setup wizard
`npm run setup`	CLI setup tool
`npm run dev`	Run in development mode with hot reload
`npm run build`	Build for production
`npm run start`	Run production build
`npm run test`	Run unit tests
`npm run test:connection`	Test connection to your Hue bridge
`npm run typecheck`	Check TypeScript types
`npm run lint`	Lint code
`npm run format`	Format code with Prettier

🔧 MCP Tools

The server provides these AI-optimized tools:

🔍 Discovery & Search Tools

Tool	Description	Example
`find_lights`	Smart search with filters	"Find all off lights", "Color bulbs in bedroom"
`list_lights`	Enhanced listing with room context	"What lights do I have?"
`get_light`	Detailed info with quick actions	"Show me the kitchen light status"

🏠 Room & Zone Management

Tool	Description	Example
`list_rooms`	List all rooms with states	"What rooms are available?"
`control_room_lights`	Control entire rooms	"Turn off the bedroom"
`list_zones`	List all zones with states	"What zones do I have?"
`control_zone_lights`	Control entire zones	"Set Main Area to relaxing"

🎭 Scene Management

Tool	Description	Example
`list_scenes`	Browse scenes with categories	"What scenes can I activate?"
`activate_scene`	Activate predefined scenes	"Activate the relax scene"

🎛️ Individual Control & Overview

Tool	Description	Example
`set_light_state`	Control with natural language	"Turn on the desk lamp to warm white"
`get_summary`	System overview with insights	"Give me a lighting summary"

✨ Enhanced Features

All tools now include:

🎯 Quick Actions - Pre-built suggestions for common tasks
💡 Smart Recommendations - Energy tips and troubleshooting
📊 Rich Context - Room relationships and capability info
🔍 Filtering & Search - Find exactly what you need
📈 Summary Statistics - Overview data for better decisions

💬 Chatbot UX Optimizations

For sustained conversation efficiency:

📏 Smart Response Sizing - compact, standard, verbose modes
🧠 Context Management - Learns preferences, adapts over time
📊 Intelligent Pagination - Never overwhelms with too much data
🎛️ Progressive Disclosure - Start minimal, expand on request
⚡ Conversation State - Tracks usage for optimal tool selection

🎨 Natural Language Examples

🔍 Smart Search Queries

"Find all kitchen lights" → Searches by room name
"Show me lights that are on" → Filters by current state
"Color bulbs in the bedroom" → Searches by capability and room
"All unreachable lights" → Finds connectivity issues

💬 Conversation Efficiency Examples

"Quick status" → Uses minimal context for fast response
"What lights do I have?" (first time) → Standard detail level
"What lights do I have?" (repeated) → Compact response
"Turn on bedroom lights" → Suggests room control over individual lights

🎨 Colors & Moods

"stormy dusk" → Deep blue-purple with low brightness
"warm white" → Comfortable warm temperature
"sunrise" → Orange-yellow with medium brightness
"ocean" → Blue-cyan colors
"fire" → Red-orange with high saturation

🌟 Atmospheric Scenes (Auto-Variation)

These keywords trigger realistic individual light variations:

"thunderstorm", "stormy" → Varied blues with different intensities
"sunset", "sunrise" → Gradient of warm colors across lights
"fireplace", "candlelight" → Flickering warm variations
"forest", "ocean" → Natural color variations
"cozy", "romantic" → Subtle warm variations

Brightness & Settings

"dim blue slowly" → Blue color with slow transition
"bright red" → Red at full brightness
"50% warm white" → Warm temperature at half brightness

Room & Zone Control

"Turn the living room to energizing mode"
"Set bedroom lights to candlelight"
"Make the office bright and cool"
"Set the Main Area zone to something relaxing for a sunday evening"
"Turn off all lights in the downstairs zone"

🏗️ Architecture

Built with modern technologies:

TypeScript - Type-safe development
node-hue-api v5 - Official Hue SDK integration
React + Vite - Modern setup wizard
Express - Setup server backend
Vitest - Fast unit testing
ESLint + Prettier - Code quality

Key Design Principles

Dual-mode operation - Cached responses with direct API fallback
Graceful degradation - Always attempts to fulfill requests
Rate limiting protection - Prevents API abuse
Comprehensive error handling - Clear, actionable error messages

🚀 Performance Optimizations

API Efficiency

60-70% fewer API calls through optimistic caching
5x longer cache lifetime (1min → 5min) with smart invalidation
Bulk operations preferred over individual light controls
Rate limiting protection with 2-minute discovery caching
Parallel execution for atmospheric variations (all lights updated simultaneously)

Chatbot Context Management

75% smaller responses in compact mode
Smart pagination - max 5-20 results based on detail level
Progressive disclosure - minimal → standard → verbose
Conversation state tracking - learns and adapts over time
Query optimization - suggests more efficient alternatives

Memory & Context Window

Adaptive response sizing based on conversation stage
Context-aware parameters automatically optimized
Intelligent truncation with clear continuation hints
Tool selection guidance for optimal efficiency

🔍 Troubleshooting

Common Issues

"No bridges found"

Ensure your Hue bridge is powered on and connected to the same network
Try manual IP entry in the setup wizard

"Authentication failed"

Make sure to press the physical button on your Hue bridge
The button must be pressed within 30 seconds of starting authentication

"Connection test failed"

Verify your bridge IP address is correct
Check that your API key is valid
Ensure your firewall allows connections to the bridge

For more help, see our Troubleshooting Guide.

🧪 Testing Your Setup

Test your configuration:

# Test connection to your bridge
npm run test:connection

# Run unit tests  
npm test

# Check TypeScript types
npm run typecheck

📄 Configuration

The server supports multiple configuration methods:

Environment variables (highest priority)
hue-config.json file
.env file (lowest priority)

Configuration Options

Variable	Description	Default
`HUE_BRIDGE_IP`	Bridge IP address	Required
`HUE_API_KEY`	API authentication key	Required
`HUE_SYNC_INTERVAL_MS`	Cache refresh interval	300000 (5 min)
`HUE_ENABLE_EVENTS`	Real-time event updates	false
`LOG_LEVEL`	Logging verbosity	info

🤝 Contributing

We welcome contributions! Please see our Development Guide for details.

Development Setup

# Clone and install
git clone https://github.com/your-username/hue-mcp.git
cd hue-mcp
npm install

# Run tests
npm test

# Start development server
npm run dev

📈 Performance

95% API call reduction through intelligent caching
Sub-second response times for cached data
Graceful fallbacks when cache is unavailable
Rate limiting protection prevents bridge overload

🔒 Security

Local network only - No external API calls except bridge discovery
No data collection - All lighting data stays local
Secure authentication - API keys stored locally
HTTPS communication with Hue bridge

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Philips Hue for the amazing smart lighting platform
node-hue-api for the excellent SDK
Model Context Protocol for the AI integration framework
Anthropic for Claude and MCP development

Made with ❤️ for the smart home community

Need help? Check our documentation or open an issue!

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

A Model Context Protocol server that enables AI assistants to control Philips Hue smart lighting systems through natural language commands.

Related MCP Servers

MCP Personal Assistant Agent
zhangzhongnan928
-
security
F
license
-
quality
A versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.
Last updated -
2
Python
Home Assistant MCP Server
miguelg719
-
security
A
license
-
quality
A Model Context Protocol server that integrates with Home Assistant to provide smart home control capabilities through natural language, supporting devices like lights, climate systems, locks, alarms, and humidifiers.
Last updated -
Python
MIT License
Hass-MCP
voska
-
security
A
license
-
quality
A Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.
Last updated -
15
Python
MIT License
Home Assistant MCP Server
oleander
-
security
A
license
-
quality
A Model Context Protocol server that allows large language models to control and query Home Assistant smart home systems through natural language interactions.
Last updated -
1
TypeScript
MIT License

View all related MCP servers