🌈 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

2. Setup Your Hue Bridge

Option A: Web Setup (Recommended)

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

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

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

🏠 Room Controls

📊 Status Checking

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

🔧 MCP Tools

The server provides these AI-optimized tools:

🔍 Discovery & Search Tools

🏠 Room & Zone Management

🎭 Scene Management

🎛️ Individual Control & Overview

🔧 Bridge & System Management

👥 User Management

✨ 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:

📄 Configuration

The server supports multiple configuration methods:

1. Environment variables (highest priority)

2. hue-config.json file

3. .env file (lowest priority)

Configuration Options

🤝 Contributing

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

Development Setup

📈 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

🛡️ User Management Security

The server includes user management tools with built-in safety protections:

• 👀 Read-only access - User tools provide visibility into bridge access without modification

• 📝 Audit trail - All user operations are logged with metadata

• 🔒 Local network only - All user data stays on your local network

Note: User deletion is not supported as Philips Hue deprecated this feature in their local API. To remove users, use the official Philips Hue Account Management web interface.

📝 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!