secretaleph/yeelight-mcp

Yeelight MCP Server

An MCP (Model Context Protocol) server for controlling Yeelight smart lamps. This server allows AI assistants like Claude to discover and control Yeelight devices on your local network, with special optimizations for the problematic W3 (YLDP005) model.

Features

• 🔍 Device Discovery: Automatically find Yeelight devices on your network
• 💡 Power Control: Turn on/off, toggle devices
• 🎨 Color Control: RGB, HSV, and color temperature adjustment
• 🌈 Color Flows: Create smooth animated color sequences
• 🎭 Scene Presets: Quick scene settings (color, HSV, temperature, auto-delay-off)
• 📊 Status Monitoring: Real-time device properties
• 🌐 Split Architecture: HTTP proxy for network access, MCP server for Claude Desktop
• ⚡ Async Operations: Fully asynchronous for better performance
• 🔧 W3 Support: Special handling for the problematic YLDP005 model

Prerequisites

• Python 3.10 or higher
• Yeelight smart lamp(s) on your local network
• LAN Control enabled on your Yeelight devices

Enabling LAN Control

Before using this server, you must enable LAN Control on your Yeelight devices:

1. Open the Yeelight app on your phone
2. Select your device
3. Go to device settings
4. Enable "LAN Control" (may be called "Developer Mode" on older versions)
5. Note your device's IP address if needed

Installation

Using uv (Recommended)

# Clone the repository
git clone https://github.com/secretaleph/yeelight-mcp.git
cd yeelight-mcp

# Install with uv
uv pip install -e .

Using pip

# Clone the repository
git clone https://github.com/secretaleph/yeelight-mcp.git
cd yeelight-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install
pip install -e .

Usage

Step 1: Start the HTTP Proxy

The HTTP proxy must be running to provide network access:

# Using uv (recommended)
uv run python -m yeelight_mcp.http_proxy

# Or with Python directly
python -m yeelight_mcp.http_proxy

This starts an HTTP server on localhost:8766 that handles all Yeelight communication.

Step 2: Configure Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "yeelight": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/yeelight-mcp",
        "python",
        "-m",
        "yeelight_mcp.mcp_client"
      ]
    }
  }
}

Or if using Python directly:

{
  "mcpServers": {
    "yeelight": {
      "command": "python",
      "args": ["-m", "yeelight_mcp.mcp_client"]
    }
  }
}

Available Tools

Device Discovery

• discover_devices - Scan network for Yeelight devices

Power Control

• turn_on - Turn on a device
• turn_off - Turn off a device
• toggle - Toggle device power state

Brightness & Color

• set_brightness - Adjust brightness (1-100)
• set_rgb - Set RGB color
• set_hsv - Set HSV color
• set_color_temp - Set color temperature (1700-6500K)

Advanced Features

• start_color_flow - Start color animation sequence with custom transitions
• stop_color_flow - Stop current animation
• set_scene_color - Set RGB color scene
• set_scene_hsv - Set HSV color scene
• set_scene_ct - Set color temperature scene
• set_scene_auto_delay_off - Set auto-delay-off scene
• get_properties - Get device status and properties

Usage Examples

After starting the HTTP proxy and configuring Claude Desktop, you can use natural language commands:

• "Discover all Yeelight devices on my network"
• "Turn on the living room light"
• "Set the bedroom lamp to 50% brightness"
• "Change the desk light to warm white (3000K)"
• "Make the lamp red"
• "Start a rainbow color flow on my lamp"
• "What's the current status of my lights?"

Resources

The server also provides MCP resources for querying device information:

• devices://list - List all discovered devices
• device://[device_id]/status - Get specific device status

Troubleshooting

Devices Not Found

1. Ensure devices are on the same network as your computer
2. Check that LAN Control is enabled in the Yeelight app
3. Try increasing the discovery timeout
4. Check firewall settings (UDP port for discovery, TCP port 55443 for control)

Connection Issues

1. Verify the device IP address
2. Ensure no firewall is blocking port 55443
3. Check that the device firmware is up to date
4. Try power cycling the device

Rate Limiting

Yeelight devices have a rate limit of 60 commands per minute. If you encounter rate limiting:

• Reduce command frequency
• Use longer transition durations
• Consider implementing command batching

Architecture

The server uses a split architecture to work around Claude Desktop's sandbox restrictions:

1. HTTP Proxy (http_proxy.py): Runs independently on port 8766 with full network access
2. MCP Client (mcp_client.py): Runs in Claude Desktop sandbox, forwards requests to HTTP proxy
3. Controller (yeelight_controller.py): Shared async control logic for device operations

This design allows Claude to control Yeelight devices despite the sandbox blocking direct network access.

Development

Project Structure

yeelight-mcp/
├── yeelight_mcp/
│   ├── __init__.py
│   ├── http_proxy.py           # HTTP proxy server (network access)
│   ├── mcp_client.py           # MCP server for Claude Desktop
│   └── yeelight_controller.py  # Core device control logic
├── pyproject.toml              # Project configuration
└── README.md                   # This file

Security Notes

• This server operates on your local network only
• Commands are not encrypted (Yeelight protocol limitation)
• Only devices with LAN Control enabled are accessible
• No cloud connectivity required

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Acknowledgments

• Built with python-yeelight library
• Uses the Model Context Protocol SDK
• Compatible with Claude Desktop and other MCP clients