Yeelight Metadata MCP Server

简体中文

Official Repository And Mirrors

GitHub is the canonical source for issues, contributions, CI, and releases. Read-only mirrors are available on Gitee and GitCode for users who cannot reach GitHub reliably, with GitLab.com as an additional global fallback. Clone from any reachable source, but report issues and contribute changes on GitHub.

This repository contains the home-understanding and management service inside Yeelight MCP. Ordinary users connect the complete Yeelight MCP suite once; they do not choose or install this server separately. Its guarded task interface covers homes, rooms, devices, groups, panels, scenes, automations, favorites, maintenance, and account operations.

Yeelight Cloud MCP Suite

Yeelight Metadata MCP and Yeelight IoT MCP form the official Yeelight MCP cloud suite. They are independently deployed services configured together by the ordinary-user setup:

Recommended composition: run one Yeelight MCP setup. It configures both services in the same AI client so the model receives home understanding, management, live state, and control without a second install or scan.

Place In Yeelight AI

yeelight-home provides the recommended installation, QR sign-in, and client-configuration flow. Ordinary users should prefer the complete yeelight-smart-home Skill. When a client cannot install Skills, one cloud setup connects the complete Yeelight MCP suite; the cloud services then execute independently of the local Runtime.

In plain language: this server gives an MCP-only AI a structured view of your home and guarded ways to manage it. It is not another CLI and it is not required by yeelight-home or the Smart Home Skill.

Highlights

• Six namespaced tools instead of a large set of low-level HTTP operations.
• 7 task groups, 23 tasks, and a runtime action catalog.
• Safe-by-default execution: dryRun defaults to true.
• Explicit confirmation for S2/S3 side effects.
• Candidate actions are blocked from live execution by default.
• MCP resources and prompts for task discovery and change planning.
• Compatible METADATA_MCP_* and legacy APP_MCP_* environment variables.

Hosted Service

The official Streamable HTTP endpoint is:

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

Required request header:

• Authorization

Recommended optional headers:

• Yeelight-Region: cn, sg, us, or eu; defaults to the deployment Region (cn by default)
• House-Id

Authorization is the only required user credential. When Yeelight-Region is absent, the server can use the JWT Region claim to select an official endpoint, then validates the complete token there. Yeelight services derive client identity from that verified authorization context; users never enter a Client ID. For actions that need a home, precedence is context.houseId -> House-Id -> first Pro home in the same Region. The fallback is request-scoped, not a global current-home state.

MCP Capabilities

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

Resources:

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

Prompts:

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

Treat the live MCP tools/list response as the source of truth for tool schemas.

Quick Start

Recommended: let Yeelight Home complete sign-in and configuration

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

The command displays the QR code. In Yeelight Pro app, tap Home's top-right +, choose MCP Authorization, and scan it. A single Pro home is selected automatically; only multiple homes require a choice by name. Replace cursor with your client or use --agent auto for detection. The generated client configuration starts a local credential proxy and contains no Authorization value. Manual token configuration remains an advanced compatibility path; never paste a token into an AI chat.

Connect to the hosted server

{
  "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>"
      }
    }
  }
}

Both optional headers may be omitted. A JWT token supplies its Region claim; opaque tokens use the deployment default. Match an explicitly selected endpoint host to the Region (api.yeelight.com, api-sg.yeelight.com, api-us.yeelight.com, or api-de.yeelight.com). To switch homes, call yeelight_metadata.list_houses, then pass the chosen ID as request.context.houseId on subsequent calls.

See the integration guide for Cursor, Claude Desktop, local source, and combined IoT/Metadata configurations.

Run from source

Requirements: Python 3.10 or newer. Python 3.12 is recommended for local development.

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

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

The local endpoint is http://127.0.0.1:9010/mcp. A request without an Authorization header returns 401 by design.

Direct startup is also supported:

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

Safety Model

Every action has an execution mode, side-effect level, status, and parameter schema.

execute_task defaults to a plan-only request:

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

Live S2/S3 execution requires confirmSideEffect=true. Candidate actions also require allowCandidate=true and are restricted by runtime policy. Start with a dry run, review plan.httpRequest, then execute only with testable or recoverable data.

Configuration

Legacy APP_MCP_* names remain supported for deployment compatibility. Standard Yeelight cloud origins support per-request Region routing. A custom API base is fixed to METADATA_MCP_DEFAULT_REGION; requests naming another Region are rejected instead of being silently misrouted.

Documentation

• Integration guide
• Usage guide
• 中文接入指南
• 中文使用指南

Development

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

The repository also includes protocol and acceptance utilities under scripts/. Live acceptance commands can change cloud data; use explicit credentials, a non-production home, and recoverable fixtures.

License

Licensed under the Apache License 2.0.