Yeelight IoT MCP Server

Yeelight IoT MCP

简体中文

官方仓库与镜像

GitHub 是问题反馈、贡献、CI 和发布的权威来源。对于无法稳定访问 GitHub 的用户，我们还提供只读镜像：Gitee 和 GitCode，以及作为额外全球备用源的 GitLab.com。可从任何可访问的源克隆，但请在 GitHub 上反馈问题并贡献更改。

重要

刚接触 Yeelight MCP？请使用一套 Yeelight MCP 配置，而不是单独安装此仓库。

该配置会同时设置此实时状态与控制服务，以及 Yeelight Metadata MCP。 对于此专用服务、端点和工具，本仓库仍是开发者参考资料。

请参阅官方英文版 Yeelight MCP 教程了解完整的新手流程，或打开简体中文教程。

Yeelight Cloud MCP 套件

本仓库是官方 Yeelight cloud MCP 套件中专注控制的部分。普通用户通过相同配置，即可将这两个独立部署的服务作为一个能力组使用：

服务	在套件中的作用	核心能力
Metadata MCP	家庭理解与受保护的管理。	广泛的发现和受保护的管理工作流、多区域授权，以及按请求选择家庭。
IoT MCP	实时状态与专注控制。	直接访问拓扑和实时状态、control_node，以及 execute_scene。

**推荐组合方式：**运行一套 Yeelight MCP 配置，即可使用这两个服务，无需再次安装或扫描。

我应该使用哪个 MCP？

需求	推荐入口
首次集成 Yeelight MCP	使用 yeelight-home setup --mode mcp --mcp-source cloud 配置完整的 Yeelight MCP 套件
家庭、房间、设备、群组、面板、场景、自动化、收藏、维护或账户工作流	Yeelight Metadata MCP
多区域授权和按请求选择家庭	Yeelight Metadata MCP，也可选择通过 Yeelight Home 进行配置
依赖 control_node 或 execute_scene 的现有集成	继续使用 Yeelight IoT MCP
开发或排查专注型直接控制、实时状态或场景执行	使用本仓库的服务和工具文档

在 Yeelight AI 中的位置

yeelight-home 提供推荐的安装、二维码登录和客户端配置流程。普通用户应优先使用完整的 yeelight-smart-home Skill；仅使用 MCP 的客户端则运行一次 cloud 配置，即可使用完整的 Yeelight MCP 套件。之后，云端服务会独立于本地 Runtime 执行。

简单来说：普通用户无需单独安装此服务。统一配置会包含此服务，同时它仍可供现有或专用集成单独访问。Yeelight Home 和任一 Skill 均不依赖此服务。

现有及专用 IoT MCP 集成

Yeelight IoT MCP 是面向 Yeelight Pro 家庭的官方专用模型上下文协议服务。它可让 MCP 客户端发现家庭、区域、房间、设备、组和场景，读取当前功能，准备安全的设备控制操作，并执行已确认的控制操作或场景。以下文档仍是现有及专用集成的受支持参考资料。

如需查看套件概览和推荐的默认设置，请返回 Yeelight Metadata MCP。

功能

• Streamable HTTP MCP 传输。
• 官方托管端点或自托管源码部署。
• 提供 8 个用于拓扑发现、设备控制和场景执行的工具。
• 区域、房间、设备、组和场景列表支持游标分页。
• 设备控制和场景执行默认采用试运行模式。
• 对控制计划进行脱敏，并明确确认副作用。

要求

• 本地部署需要 Python 3.10 或更高版本。
• 按文档中的本地工作流操作需要 uv。
• Yeelight Authorization 令牌。区域和 House ID 为可选项。

推荐：让 Yeelight Home 完成登录和配置

npm install --global yeelight-home
yeelight-home setup --lang en-US --mode mcp --agent cursor --mcp-source cloud --yes

该命令会显示二维码。在 Yeelight Pro 应用的 Home 页面中，点击右上角的 +，选择 MCP Authorization，然后扫描二维码。系统会自动选择一个 Pro 家庭；如果有多个家庭，则会按名称列出。云模式会通过本地凭据代理同时配置 Metadata 和 IoT MCP，无需将 Authorization 复制到 AI 客户端的配置中。手动配置令牌仍可作为高级兼容方案使用。

托管服务

使用官方 Streamable HTTP 端点：

https://api.yeelight.com/apis/mcp_server/v1/mcp

必需的请求头：

Authorization: <YOUR_AUTHORIZATION>

可选请求头为 Yeelight-Region 和 House-Id。服务接受原始令牌或带有 Bearer 前缀的令牌。省略 Region 时，会先根据 JWT Region 声明选择官方端点，再验证完整令牌。省略 House ID 时，服务会选择该 Region 中第一个 Pro 家庭。用户无需配置 Client ID；IoT 上游调用会在需要时从已验证的 JWT 中获取该 ID，如果没有，则在开发 Region 中使用 dev，在 cn、sg、us 或 eu 中使用 iot-app。

本地开发

git clone https://github.com/Yeelight/yeelight-iot-mcp.git
cd yeelight-iot-mcp

uv sync --extra test
YEELIGHT_IOT_MCP_RUNTIME_ENV=local \
YEELIGHT_IOT_MCP_NACOS_ENABLED=false \
PYTHONPATH=src \
uv run uvicorn main:streamable_http_app --host 127.0.0.1 --port 9000

本地 MCP URL 为 http://127.0.0.1:9000/mcp。本地部署仍会使用 Yeelight 云 API，并非离线网关。无论绑定地址或运行时环境如何，每个请求都必须提供明确的 Authorization 请求头。服务不会读取操作者的 CLI Profile；测试可以使用明确指定的隔离凭据提供程序。公共项目默认禁用 Nacos 注册，可通过环境变量显式启用。

MCP 客户端配置

{
  "mcpServers": {
    "yeelight-iot": {
      "url": "https://api.yeelight.com/apis/mcp_server/v1/mcp",
      "headers": {
        "Authorization": "<YOUR_AUTHORIZATION>"
      }
    }
  }
}

更改配置后，请重启 MCP 客户端，然后确认 tools/list 返回 Yeelight 工具。

工具

工具	用途	副作用
get_currnet_house_info	读取所选家庭。为保持兼容性，保留了拼写错误。	只读
get_areas	使用游标分页列出区域。	只读
get_rooms	使用游标分页列出房间。	只读
get_devices	列出所有设备，或按房间筛选。	只读
get_groups	列出所有组，或按房间筛选。	只读
get_scenes	使用游标分页列出场景。	只读
control_node	预览或执行节点属性命令。	默认采用试运行模式
execute_scene	预览或执行场景。	默认采用试运行模式

如需查看请求示例和操作规则，请阅读使用指南。 如需了解客户端和部署详情，请阅读集成指南。

安全模型

control_node 和 execute_scene 默认使用 dryRun=true。执行实时操作 需要同时设置 dryRun=false 和 confirmSideEffect=true。调用方应：

1. 使用读取工具将名称解析为当前 ID。
2. 检查目标支持的属性和运算符。
3. 生成并审核试运行计划。
4. 在调用应用中获取用户确认。
5. 执行一次，并在可能的情况下查询结果状态。

当前安全策略会阻止控制属性 rs。不要盲目重试失败的写入或场景执行。

配置

本地部署常用的环境变量：

变量	默认值	用途
YEELIGHT_IOT_MCP_API_BASE_URL	https://api.yeelight.com	Yeelight API 源
YEELIGHT_IOT_MCP_DEFAULT_REGION	cn	不透明令牌的回退 Region
YEELIGHT_IOT_MCP_BIND_HOST	127.0.0.1 in local/test	绑定地址；生产环境默认使用 0.0.0.0
YEELIGHT_IOT_MCP_PATH	/mcp	Streamable HTTP 路径
YEELIGHT_IOT_MCP_HTTP_TIMEOUT	15	上游超时时间，单位为秒
YEELIGHT_IOT_MCP_FETCH_NODES_MAX_SIZE	300	列表页大小上限
YEELIGHT_IOT_MCP_NACOS_ENABLED	false	启用可选的服务注册
YEELIGHT_IOT_MCP_LOG_DIR	./logs/yeelight-online-iot-mcp-server	日志目录

测试

uv run --extra test pytest -q

测试涵盖 JWT 声明处理、多 Region 路由、本地 Profile 隔离、Pro Home 回退、授权规范化、分页、计划脱敏、试运行默认设置、确认保护和配置覆盖。测试不会调用 Yeelight 云服务。

许可证

Apache License 2.0。参见 LICENSE 和 NOTICE。