Yeelight MCP

Yeelight MCP服务器

用于控制Yeelight智能灯的MCP（模型上下文协议）服务器。该服务器允许像Claude这样的人工智能助手发现和控制本地网络上的Yeelight设备，并对有问题的W3（YLDP005）模型进行了特殊优化。

特性

• 🔍 设备发现：自动查找网络上的Yeelight设备
• 💡 功率控制：打开/关闭，切换设备
• 🎨 色彩控制：RGB、HSV和色温调节
• 🌈 色彩流动：创建平滑的动画颜色序列
• 🎭 场景预设：快速场景设置（颜色、HSV、温度、自动延迟关闭）
• 📊 状态监测：实时设备属性
• 🌐 分离式架构：用于网络访问的HTTP代理，用于Claude Desktop的MCP服务器
• ⚡ 异步操作：完全异步以获得更好的性能
• 🔧 W3支持：有问题的YLDP005型号的特殊处理

先决条件

• Python 3.10或更高版本
• Yeelight本地网络上的智能灯
• Yeelight设备上启用了LAN控制

启用LAN控制

在使用此服务器之前，您必须在Yeelight设备上启用LAN控制：

1. 在手机上打开Yeelight应用程序
2. 选择您的设备
3. 转到设备设置
4. 启用“LAN控制”（在旧版本上可能称为“开发人员模式”）
5. 如果需要，请记下设备的IP地址

安装

使用紫外线（推荐）

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

# Install with uv
uv pip install -e .

使用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 .

用法

步骤1:启动HTTP代理

HTTP代理必须正在运行才能提供网络访问：

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

# Or with Python directly
python -m yeelight_mcp.http_proxy

这将在上启动HTTP服务器 localhost:8766 处理所有Yeelight通信。

步骤2：配置Claude桌面

添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

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

或者直接使用Python：

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

可用工具

设备发现

• discover_devices -扫描Yeelight设备的网络

功率控制

• turn_on -打开设备
• turn_off -关闭设备
• toggle -切换设备电源状态

亮度和颜色

• set_brightness -调整亮度（1-100）
• set_rgb -设置RGB颜色
• set_hsv -设置HSV颜色
• set_color_temp -设定色温（1700-6500K）

高级功能

• start_color_flow -使用自定义过渡开始颜色动画序列
• stop_color_flow -停止当前动画
• set_scene_color -设置RGB色彩场景
• set_scene_hsv -设置HSV颜色场景
• set_scene_ct -设置色温场景
• set_scene_auto_delay_off -设置场景外的自动延迟
• get_properties -获取设备状态和属性

使用示例

启动HTTP代理并配置Claude Desktop后，您可以使用自然语言命令：

• “发现我网络上的所有Yeelight设备”
• “打开客厅的灯”
• “将卧室灯设置为50%亮度”
• “将台灯换成暖白色（3000K）”
• “让灯变红”
• “在我的灯上开始彩虹色的流动”
• “我的灯的当前状态如何？”

资源

服务器还提供MCP资源用于查询设备信息：

• devices://list -列出所有发现的设备
• device://[device_id]/status -获取特定设备状态

故障排除

未找到设备

1. 确保设备与计算机位于同一网络上
2. 检查Yeelight应用程序中是否启用了LAN控制
3. 尝试增加发现超时时间
4. 检查防火墙设置（UDP端口用于发现，TCP端口55443用于控制）

连接问题

1. 验证设备IP地址
2. 确保没有防火墙阻止端口55443
3. 检查设备固件是否为最新版本
4. 尝试重启设备

速率限制

Yeelight设备的速率限制为每分钟60个命令。如果遇到速率限制：

• 降低命令频率
• 使用更长的过渡持续时间
• 考虑实现命令批处理

建筑

服务器使用拆分架构来绕过Claude Desktop的沙盒限制：

1. HTTP 代理 (http_proxy.py)：在端口8766上独立运行，具有完全网络访问权限
2. MCP客户端 (mcp_client.py)：在Claude Desktop沙盒中运行，将请求转发到HTTP代理
3. 控制器 (yeelight_controller.py)：设备操作的共享异步控制逻辑

这种设计允许Claude控制Yeelight设备，尽管沙盒阻止了直接的网络访问。

发展

项目结构

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

安全说明

• 此服务器仅在您的本地网络上运行
• 命令未加密（Yeelight协议限制）
• 只有启用了LAN控制的设备才能访问
• 无需云连接

贡献

欢迎投稿！请随时提交拉取请求。

许可证

麻省理工学院

致谢

• 内置于 python yeelight 图书馆
• 使用 模型上下文协议 软件开发工具包
• 兼容 克劳德桌面版 以及其他MCP客户端