🌈 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

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

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

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

# 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

🛡️ 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!