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:

Server	Role in the suite	Core capabilities
Metadata MCP	Home understanding and guarded management.	Broad discovery and guarded management workflows, multi-region authorization, and request-scoped home selection.
IoT MCP	Live state and focused control.	Direct topology and live-state access, control_node, and execute_scene.

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

Which MCP should I use?

What you need	Recommended entry point
First Yeelight MCP integration	Configure the complete Yeelight MCP suite with yeelight-home setup --mode mcp --mcp-source cloud
Homes, rooms, devices, groups, panels, scenes, automations, favorites, maintenance, or account workflows	Yeelight Metadata MCP
Multi-region authorization and request-scoped home selection	Yeelight Metadata MCP, optionally configured with Yeelight Home
An existing integration that depends on control_node or execute_scene	Keep using Yeelight IoT MCP
Develop or troubleshoot focused direct control, live state, or scene execution	Use this repository's server and tool documentation

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

Tool	Purpose	Side effect
get_currnet_house_info	Read the selected house. The misspelling is retained for compatibility.	Read only
get_areas	List areas with cursor pagination.	Read only
get_rooms	List rooms with cursor pagination.	Read only
get_devices	List all devices or filter by room.	Read only
get_groups	List all groups or filter by room.	Read only
get_scenes	List scenes with cursor pagination.	Read only
control_node	Preview or execute a node property command.	Dry-run by default
execute_scene	Preview or execute a scene.	Dry-run by default

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:

Variable	Default	Purpose
YEELIGHT_IOT_MCP_API_BASE_URL	https://api.yeelight.com	Yeelight API origin
YEELIGHT_IOT_MCP_DEFAULT_REGION	cn	Fallback Region for opaque tokens
YEELIGHT_IOT_MCP_BIND_HOST	127.0.0.1 in local/test	Bind address; production defaults to 0.0.0.0
YEELIGHT_IOT_MCP_PATH	/mcp	Streamable HTTP path
YEELIGHT_IOT_MCP_HTTP_TIMEOUT	15	Upstream timeout in seconds
YEELIGHT_IOT_MCP_FETCH_NODES_MAX_SIZE	300	Maximum list page size
YEELIGHT_IOT_MCP_NACOS_ENABLED	false	Enable optional service registration
YEELIGHT_IOT_MCP_LOG_DIR	./logs/yeelight-online-iot-mcp-server	Log directory

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.