# Yeelight Metadata MCP Server [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Yeelight/yeelight-metadata-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/yeelight-metadata-mcp-server

## Description
Yeelight home metadata and guarded management workflows.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "yeelight-metadata-mcp-server": {
    "url": "https://api.yeelight.com/apis/metadata_mcp_server/v1/mcp"
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/yeelight-metadata-mcp-server/readme_