Yeelight Metadata MCP Server

Yeelight Metadata MCP 服务

简体中文

官方仓库和镜像

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

此仓库包含 Yeelight MCP 中的家庭理解和管理服务。普通用户只需连接一次完整的 Yeelight MCP 套件，无需单独选择或安装此服务。其受保护的任务接口涵盖家庭、房间、设备、群组、面板、场景、自动化、收藏、维护和账户操作。

提示

刚接触 Yeelight MCP？请参阅官方英文 Yeelight MCP 教程，了解如何准备 Yeelight Home、连接完整的 Metadata 和 IoT 能力套件，并验证首个实际响应。另有简体中文教程可供参考。

Yeelight Cloud MCP 套件

Yeelight Metadata MCP 和 Yeelight IoT MCP 组成 Yeelight 官方 MCP 云套件。它们是独立部署的服务，通过普通用户设置进行统一配置：

服务	在套件中的作用	核心能力
Metadata MCP	家庭理解和受保护的管理。	面向家庭、房间、设备、群组、面板、场景、自动化、收藏、维护、账户、多区域授权和按请求选择家庭的广泛发现能力与受保护工作流。
IoT MCP	实时状态和专注控制。	直接访问拓扑结构和实时状态，通过 control_node 控制设备，并通过 execute_scene 执行场景。

**推荐组合：**运行一次 Yeelight MCP 设置。该设置会在同一个 AI 客户端中配置这两个服务，使模型无需再次安装或扫描即可获得家庭理解、管理、实时状态和控制能力。

在 Yeelight AI 中的定位

yeelight-home 提供推荐的安装、二维码登录和客户端配置流程。普通用户应优先使用完整的 yeelight-smart-home Skill。当客户端无法安装 Skills 时，可通过一次云端设置连接完整的 Yeelight MCP 套件；随后，云服务会独立于本地 Runtime 执行。

简而言之，此服务为仅支持 MCP 的 AI 提供结构化的家庭视图和受保护的管理方式。它不是另一个 CLI，也不是 yeelight-home 或 Smart Home Skill 的必需组件。

适合在以下情况下选择	以下情况下请选择其他方案
你的 AI 客户端支持 MCP，但无法安装 Agent Skills。	你的客户端可以安装 Skills：使用 yeelight-smart-home 获取完整的引导式体验。
AI 需要管理房间、设备、群组、场景、自动化、面板或家庭。	你要在终端中编写脚本或排查问题：直接使用 yeelight-home。
你需要开发或排查 Yeelight MCP 中的家庭理解服务。	你只需要现有的专用 control_node 或 execute_scene 集成：请参阅 IoT 服务文档。

亮点

• 使用 6 个带命名空间的工具，取代大量底层 HTTP 操作。
• 包含 7 个任务组、23 个任务和运行时操作目录。
• 默认安全执行：dryRun 的默认值为 true。
• S2/S3 副作用需要明确确认。
• 默认禁止候选操作在线上执行。
• 提供 MCP 资源和提示词，用于发现任务和规划变更。
• 兼容 METADATA_MCP_* 和旧版 APP_MCP_* 环境变量。

托管服务

官方 Streamable HTTP 端点为：

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

必需的请求标头：

• Authorization

建议使用的可选标头：

• Yeelight-Region：cn、sg、us 或 eu；默认为部署区域（默认为 cn）
• House-Id

Authorization 是唯一必需的用户凭据。缺少 Yeelight-Region 时，服务 可以使用 JWT 的区域声明来选择官方端点，然后在该端点验证完整令牌。 Yeelight 服务会从经过验证的授权上下文中获取客户端身份；用户无需输入 Client ID。对于需要家庭的操作，优先级依次为 context.houseId -> House-Id -> 同一区域内的首个 Pro 家庭。此回退仅适用于当前请求，不会 设置全局的当前家庭状态。

MCP 功能

工具：

• yeelight_metadata.list_groups
• yeelight_metadata.list_houses
• yeelight_metadata.list_tasks
• yeelight_metadata.list_actions
• yeelight_metadata.get_action_schema
• yeelight_metadata.execute_task

资源：

• yeelight-metadata://tasks
• yeelight-metadata://actions
• yeelight-metadata://schema/{task}/{action}

提示词：

• yeelight_metadata.inspect_home_metadata
• yeelight_metadata.plan_metadata_change
• yeelight_metadata.troubleshoot_automation_metadata

请将实时 MCP tools/list 响应作为工具架构的准确信息来源。

快速开始

推荐：让 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 家庭；只有 存在多个家庭时，才需要按名称选择。请将 cursor 替换为你的客户端，或使用 --agent auto 进行检测。生成的客户端配置会启动本地凭据代理，且不包含 Authorization 值。手动配置令牌仍是高级兼容方案；切勿将令牌粘贴到 AI 聊天中。

连接到托管服务

{
  "mcpServers": {
    "yeelight-metadata": {
      "url": "https://api.yeelight.com/apis/metadata_mcp_server/v1/mcp",
      "headers": {
        "Authorization": "<YOUR_AUTHORIZATION>",
        "Yeelight-Region": "cn",
        "House-Id": "<YOUR_HOUSE_ID>"
      }
    }
  }
}

两个可选标头均可省略。JWT 令牌会提供其区域声明； 不透明令牌则使用部署默认区域。若明确选择端点，请确保主机与区域匹配 （api.yeelight.com、api-sg.yeelight.com、api-us.yeelight.com 或 api-de.yeelight.com）。若要切换家庭，请调用 yeelight_metadata.list_houses， 然后在后续调用中将选定的 ID 作为 request.context.houseId 传入。

请参阅集成指南，了解 Cursor、Claude Desktop、 本地源码以及 IoT/Metadata 组合配置。

从源码运行

要求：Python 3.10 或更高版本。本地开发建议使用 Python 3.12。

uv venv .venv
source .venv/bin/activate
uv pip install -e '.[test]'

METADATA_MCP_RUNTIME_ENV=local ./service.sh start
./service.sh status

本地端点为 http://127.0.0.1:9010/mcp。按设计，不带 Authorization 标头的请求会返回 401。

也支持直接启动：

METADATA_MCP_RUNTIME_ENV=local \
METADATA_MCP_BIND_HOST=127.0.0.1 \
PYTHONPATH=src \
.venv/bin/uvicorn main:streamable_http_app --host 127.0.0.1 --port 9010

安全模型

每个操作都有执行模式、副作用级别、状态和参数架构。

级别	含义	示例
S0	只读	list、get、search
S1	诊断或外部活动	diagnose、download、poll
S2	创建或更新	create、update、configure
S3	破坏性操作或涉及身份的操作	delete、unbind、transfer、login

execute_task 默认仅生成计划：

{
  "request": {
    "task": "family_space.manage_room",
    "action": "create",
    "payload": {"name": "Sample Room"},
    "options": {"dryRun": true}
  }
}

在线执行 S2/S3 操作需要设置 confirmSideEffect=true。候选操作还需要设置 allowCandidate=true，并受运行时策略限制。请先进行试运行，检查 plan.httpRequest，然后仅使用可测试或可恢复的数据执行操作。

配置

变量	默认值	用途
METADATA_MCP_RUNTIME_ENV	prod	prod、dev、local 或 test
METADATA_MCP_BIND_HOST	local/test: 127.0.0.1; prod/dev: 0.0.0.0	监听地址
METADATA_MCP_PORT	9010	监听端口
METADATA_MCP_PATH	/mcp	MCP 路由
METADATA_MCP_DEFAULT_REGION	cn	未提供 Yeelight-Region 时使用的默认区域
METADATA_MCP_HOST_PREFIX	https://api.yeelight.com	Yeelight API 主机
METADATA_MCP_API_BASE_URL	主机前缀	显式 API 基础 URL
METADATA_MCP_HTTP_TIMEOUT	15	上游超时时间（秒）
METADATA_MCP_RESOURCE_DIR	resources/catalog	运行时目录覆盖项
METADATA_MCP_NACOS_ENABLE	取决于环境	Nacos 注册开关
METADATA_MCP_NACOS_SERVER	取决于环境	Nacos 服务
METADATA_MCP_ALLOW_CANDIDATE_EXECUTION	false	候选项执行开关

为兼容部署，仍支持旧版 APP_MCP_* 名称。 标准 Yeelight 云端源支持按请求进行区域路由。自定义 API 基础 URL 固定使用 METADATA_MCP_DEFAULT_REGION；请求中指定其他 区域时将被拒绝，而不会被错误路由。

文档

• 集成指南
• 使用指南
• 中文接入指南
• 中文使用指南

开发

PYTHONPATH=src python -m pytest -q
python -m compileall -q main.py src tests scripts

仓库还在 scripts/ 下提供协议和验收工具。 实时验收命令可能会更改云端数据；请使用明确的凭据、 非生产环境的家庭设备，以及可恢复的测试夹具。

许可证

根据 Apache 许可证 2.0 授权。