Yeelight Metadata MCP Server

简体中文

An MCP server for Yeelight home metadata and management workflows. It gives AI clients a guarded task interface for homes, rooms, devices, device groups, panels, scenes, automations, favorites, maintenance, and account operations.

Use Yeelight IoT MCP for device control and live state. Use this server when the intent is to create, update, organize, configure, bind, unbind, or inspect application metadata.

Yeelight AI Capability Matrix

These projects form a complementary stack. Choose the entry point that matches how you integrate with Yeelight; they can also be combined.

Typical paths: terminal users and scripts -> yeelight-ai; MCP clients -> IoT MCP and/or Metadata MCP; agent hosts -> Yeelight Smart Home Skill -> yeelight-home. PRO App Builder also uses proven yeelight-home capabilities when generating local applications.

Related MCP server: guesty-mcp-server

Highlights

• Five 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:

• Client-Id

• House-Id

House-Id is used as the default global home context. An explicit context.houseId in a tool request takes precedence.

MCP Capabilities

Tools:

• yeelight_metadata.list_groups

• 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

Connect to the hosted server

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

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:

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

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.