Hue MCP Server

A production-ready Model Context Protocol (MCP) server that enables Claude to control Philips Hue lights through natural language commands. Built with FastMCP framework and designed for seamless integration with Claude Desktop.

Features

• 🏠 Room-based Control: Control current Hue rooms, zones, and groups by name or ID

• 💡 Individual Light Control: Control any light ID returned by the bridge

• 🔍 Light Discovery: List all lights and get their current states

• 🌉 Bridge Integration: Discover and test connectivity to Hue bridge

• ⚡ High Performance: Async operations with connection pooling and rate limiting

• 🛡️ Error Handling: Comprehensive error handling with retry logic

• 📊 Production Ready: Full test coverage, logging, and monitoring

Related MCP server: IntelliGlow

Available MCP Tools

Rooms and Lights

The bridge is the source of truth. No light IDs, room names, or memberships are configured in code, and inventory is fetched on each request.

• Call hue_list_lights for current light IDs and states.

• Call hue_list_rooms for current rooms, zones, and groups with IDs and membership.

• Pass a group ID or name to hue_control_room. Names are case-insensitive; underscores can replace spaces (for example, living_room).

• If multiple groups share a name, use the group ID to select one explicitly.

• all or 0 targets every light currently on the bridge.

• Positive light IDs are checked by the bridge, including IDs above 17. Missing lights return the bridge's error.

New lights and Hue app room edits take effect on the next request without a restart. Room names from older local mappings must now match an actual bridge group.

Supported Actions

• on - Turn lights on

• off - Turn lights off

• toggle - Toggle light state

Installation

Prerequisites

• Python 3.10 or higher

• Philips Hue Bridge on local network

• Bridge username (already configured for IP 192.168.1.64)

Install Dependencies

# Install the package
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Environment Configuration

1. Copy the environment template:

   cp .env.example .env

2. Edit .env file if needed (default values work for the configured setup):

   HUE_BRIDGE_IP=192.168.1.64
   HUE_USERNAME=cJdzxhKlxr2h92jwDkTv-DvpOxglPxn147UEg1Gp
   LOG_LEVEL=INFO

Usage

Running the MCP Server

# Run directly
python -m hue_mcp

# Or using the console script
hue-mcp

Claude Desktop Integration

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "hue-control": {
      "command": "python",
      "args": ["-m", "hue_mcp"],
      "cwd": "/path/to/hue-mcp-server"
    }
  }
}

Natural Language Examples

Once integrated with Claude Desktop, you can use natural language commands:

• "Turn on the kitchen lights" → Turns on the bridge's current kitchen members

• "Set office light to 50% brightness" → Dims office light (ID 7) to ~127 brightness

• "Turn off all lights" → Turns off all lights using group control

• "What lights are currently on?" → Lists all lights with their current states

• "Toggle the bedroom lights" → Toggles lights 1 and 4

Testing

Run Unit Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=term-missing

# Run specific test file
pytest tests/test_hue_client.py -v

Test Bridge Connectivity

# Test basic connectivity
python -c "
import asyncio
from src.hue_mcp.hue_client import AsyncHueClient

async def test():
    async with AsyncHueClient() as client:
        success = await client.test_connection()
        print(f'Bridge connection: {\"SUCCESS\" if success else \"FAILED\"}')

asyncio.run(test())
"

Development

Code Quality

# Linting and formatting
ruff check src/ --fix
ruff format src/

# Type checking
mypy src/

# Run all quality checks
ruff check . --fix && mypy src/ && ruff format .

Project Structure

hue-mcp-server/
├── src/hue_mcp/
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # CLI entry point
│   ├── server.py            # Main MCP server
│   ├── hue_client.py        # Async HTTP client with rate limiting
│   ├── light_manager.py     # Business logic and room mappings
│   ├── config.py            # Configuration management
│   └── tools/               # MCP tool implementations
│       ├── light_control.py # Individual light control
│       ├── room_control.py  # Room-based control
│       └── discovery.py     # Light discovery and bridge testing
├── tests/                   # Comprehensive test suite
├── pyproject.toml           # Project configuration
├── README.md               # This file
└── .env.example            # Environment template

Performance

• Light Operations: Under 1 second response time

• Room Operations: Under 3 seconds for multiple lights

• Rate Limiting: 10 light operations/second, 1 group operation/second

• Connection Pooling: Optimized HTTP connections with keepalive

• Concurrent Operations: Up to 5 concurrent light operations per room

Error Handling

The server includes comprehensive error handling for:

• Network Issues: Connection timeouts, DNS failures

• Bridge Errors: Invalid light IDs, bridge unavailable

• Rate Limiting: Automatic retry with exponential backoff

• Validation Errors: Invalid parameters, out-of-range values

Configuration

Environment Variables

Troubleshooting

Common Issues

Bridge Not Found

Error: Failed to connect to Hue bridge at 192.168.1.64
Solution: Verify bridge IP and network connectivity

Authentication Failed

Error: Invalid username/authentication
Solution: Verify HUE_USERNAME in .env file

Rate Limiting

Warning: Rate limited, retrying...
Solution: Normal behavior, requests will retry automatically

Debugging

Enable debug logging:

export LOG_LEVEL=DEBUG
python -m hue_mcp

Bridge Information

• IP Address: 192.168.1.64

• Username: cJdzxhKlxr2h92jwDkTv-DvpOxglPxn147UEg1Gp

• Light IDs: Discovered from the bridge

• Rooms and Groups: Discovered from the bridge

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository

2. Create a feature branch

3. Make changes with tests

4. Run quality checks: ruff check . --fix && mypy src/ && pytest

5. Submit a pull request

Built with ❤️ using FastMCP and designed for seamless Claude integration.

FastMCP is pinned to the version verified by the test suite and live deployment. Upgrade it deliberately with the MCP integration tests.

Deployment on dev.local

The active service is hue-mcp in ~/nosuch/mcp-gateway/docker-compose.yml, built from this repository. Rebuild only that service after pulling changes:

cd ~/nosuch/mcp-gateway
docker compose up -d --build --no-deps hue-mcp

Do not run the standalone Compose service alongside it: both bind host port 8000.