Yeelight Metadata MCP Server

What Yeelight Metadata MCP Server MCP server does

Yeelight Metadata MCP Server MCP server provides an MCP interface for understanding and managing Yeelight homes. Its scope includes homes, rooms, devices, groups, panels, scenes, automations, favorites, maintenance, accounts, multi-region authorization, and request-scoped home selection.

The service is one part of the Yeelight MCP cloud suite. The companion Yeelight IoT MCP service handles direct topology and live-state access, device control through control_node, and scene execution through execute_scene. This metadata service is intended for home discovery and guarded management rather than low-level device control.

How it works

The server exposes six namespaced tools:

• 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

MCP resources expose task, action, and task-action schema information. Prompts support home metadata inspection, metadata-change planning, and automation-metadata troubleshooting. The live tools/list response should be treated as the authoritative source for current tool schemas.

Task execution uses action metadata that includes an execution mode, side-effect level, status, and parameter schema. Read-only work is classified as S0; diagnostic or external activity as S1; create and update operations as S2; and destructive or identity-sensitive operations as S3.

Requests default to planning mode with dryRun: true. A plan can expose the intended HTTP request before execution. Live S2 or S3 operations require confirmSideEffect=true, and candidate actions additionally require allowCandidate=true subject to runtime policy.

Setup and configuration

The hosted Streamable HTTP endpoint is https://api.yeelight.com/apis/metadata_mcp_server/v1/mcp. Requests require an Authorization header. Yeelight-Region can select cn, sg, us, or eu, while House-Id can identify a home. Both are optional: the token or deployment supplies the region, and home selection can fall back to the first Pro home in that region.

Yeelight Home can complete sign-in and client configuration with its MCP setup flow. The documented example targets Cursor, and the integration guide also covers Claude Desktop, local source, and combined IoT/Metadata configurations. Manual token configuration is supported as an advanced path; credentials should not be pasted into an AI chat.

For local development, use Python 3.10 or newer, with Python 3.12 recommended. Install the project in an environment created with uv, then start it with METADATA_MCP_RUNTIME_ENV=local. The local endpoint defaults to http://127.0.0.1:9010/mcp.

Tools and capabilities

The task catalog contains seven task groups, 23 tasks, and a runtime action catalog. Home selection is request-scoped: callers can list homes, then pass a selected ID as request.context.houseId on later calls. The service supports multiple official regions and validates authorization against the selected deployment.

The six tools divide discovery from execution. Listing tools reveal available homes, groups, tasks, and actions; the schema tool describes a selected action; and execute_task submits a structured task request. Resources and prompts provide additional ways for an MCP client to inspect available work and prepare changes.

Limitations and notes

This service is not a standalone command-line interface and ordinary Yeelight users generally install the complete Yeelight MCP setup rather than selecting this service separately. Clients that can install the yeelight-smart-home Skill may prefer that guided experience, while terminal scripting and troubleshooting use yeelight-home directly.

The metadata service does not replace the IoT service for live state, direct device control, or scene execution. A request without Authorization receives HTTP 401 by design. Before permitting side effects, review the dry-run plan and use recoverable or test data where possible.