Yeelight IoT MCP Server

Yeelight IoT MCP

简体中文

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.

[!IMPORTANT] New to Yeelight MCP? Use one Yeelight MCP setup instead of installing this repository separately.

The setup configures this live-state/control service and Yeelight Metadata MCP together. This repository remains the developer reference for its specialized server, endpoint, and tools.

Follow the official English Yeelight MCP tutorial for the complete beginner path, or open the Simplified Chinese tutorial.

Yeelight Cloud MCP Suite

This repository is the focused-control part of the official Yeelight cloud MCP suite. Ordinary users receive both independently deployed services as one capability group through the same setup:

Recommended composition: run one Yeelight MCP setup so both services are available without a second install or scan.

Which MCP should I use?

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; MCP-only clients run one cloud setup for the complete Yeelight MCP suite. The cloud services then execute independently of the local Runtime.

In plain language: ordinary users do not install this server separately. It is included by the unified setup and remains independently addressable for existing or specialized integrations. It is not a dependency of Yeelight Home or either Skill.

Existing and specialized IoT MCP integrations

Yeelight IoT MCP is the official focused Model Context Protocol server for Yeelight Pro homes. It lets MCP clients discover homes, areas, rooms, devices, groups, and scenes, read current capabilities, prepare safe device controls, and execute confirmed controls or scenes. The following documentation remains the supported reference for existing and specialized integrations.

For the suite overview and recommended default setup, return to Yeelight Metadata MCP.

Capabilities

• Streamable HTTP MCP transport.
• Official hosted endpoint or self-hosted source deployment.
• Eight tools for topology discovery, device control, and scene execution.
• Cursor pagination for area, room, device, group, and scene lists.
• Dry-run by default for device control and scene execution.
• Redacted control plans and explicit side-effect confirmation.

Requirements

• Python 3.10 or later for local deployment.
• uv for the documented local workflow.
• A Yeelight Authorization token. Region and House ID are optional.

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 a QR code. In Yeelight Pro app Home, tap the top-right +, choose MCP Authorization, and scan it. One Pro home is selected automatically; multiple homes are presented by name. Cloud mode configures Metadata and IoT MCP together through local credential proxies, without copying Authorization into the AI client's configuration. Manual token configuration remains an advanced compatibility path.

Hosted Service

Use the official Streamable HTTP endpoint:

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

Required request header:

Authorization: <YOUR_AUTHORIZATION>

Optional headers are Yeelight-Region and House-Id. The server accepts a raw token or a value prefixed with Bearer. When Region is omitted, a JWT Region claim selects the official endpoint before the complete token is validated. When House ID is omitted, the server selects the first Pro home in that Region. Users never configure a Client ID; IoT upstream calls derive it from the validated JWT when required, falling back to dev in the development Region and iot-app in cn, sg, us, or eu.

Local Development

git clone https://github.com/Yeelight/yeelight-iot-mcp.git
cd yeelight-iot-mcp

uv sync --extra test
YEELIGHT_IOT_MCP_RUNTIME_ENV=local \
YEELIGHT_IOT_MCP_NACOS_ENABLED=false \
PYTHONPATH=src \
uv run uvicorn main:streamable_http_app --host 127.0.0.1 --port 9000

The local MCP URL is http://127.0.0.1:9000/mcp. Local deployment still uses Yeelight cloud APIs; it is not an offline gateway. Every request must provide an explicit Authorization header regardless of bind address or runtime environment. The service never reads an operator's CLI Profile; tests may use an explicit isolated credential provider. Nacos registration is disabled by default in the public project and can be enabled explicitly through environment variables.

MCP Client Configuration

{
  "mcpServers": {
    "yeelight-iot": {
      "url": "https://api.yeelight.com/apis/mcp_server/v1/mcp",
      "headers": {
        "Authorization": "<YOUR_AUTHORIZATION>"
      }
    }
  }
}

Restart the MCP client after changing its configuration, then verify that tools/list returns the Yeelight tools.

Tools

For request examples and operating rules, read the usage guide. For client and deployment details, read the integration guide.

Safety Model

control_node and execute_scene default to dryRun=true. A live operation requires both dryRun=false and confirmSideEffect=true. Callers should:

1. Resolve names to current IDs using read tools.
2. Inspect the target's supported properties and operators.
3. Generate and review a dry-run plan.
4. Obtain user confirmation in the calling application.
5. Execute once and query the resulting state when possible.

The control property rs is blocked by the current safety policy. Do not retry failed writes or scene executions blindly.

Configuration

Common environment variables for local deployments:

Test

uv run --extra test pytest -q

Tests cover JWT claim handling, multi-Region routing, local Profile isolation, Pro home fallback, authorization normalization, pagination, redacted plans, dry-run defaults, confirmation guards, and configuration overrides. They do not call the live Yeelight cloud.

License

Apache License 2.0. See LICENSE and NOTICE.