Yeelight IoT MCP Server

io.github.YeelightPublished by GitHub account Yeelightv0.1.0Updated Oct 25, 2026

Yeelight device discovery, state, control, and scene execution.

VerifiedStreamable HTTPWeb executableLocation & LifestyleProductivity & Workflow

Overview

AI-generated overview

Official Yeelight cloud MCP server that lets an assistant discover a Yeelight Pro home's rooms, devices, groups and scenes, and preview or execute device and 場景

What you can do
Read the selected home and list areas, rooms, devices, groups and scenes, with cursor pagination and optional room filtering for devices and groups. Preview or execute a node property command on a device, dry-run by default. Preview or execute a scene, dry-run by default.
When to use it
Use it when an existing or specialized integration needs direct live-state access and focused control of a Yeelight Pro home, including the control_node and execute_scene tools. Ordinary users are steered to the combined Yeelight MCP setup instead of installing this server separately.
Requirements
Remote Streamable HTTP endpoint at the official Yeelight API host, or a local Python 3.10+ deployment with uv. A Yeelight Authorization token is required on every request; Yeelight-Region and House-Id headers are optional. Local deployment still calls Yeelight cloud APIs and is not an offline gateway.
Before you install
The Authorization bearer token is a credential and must be supplied on every request; the recommended setup avoids copying it into client configuration. control_node and execute_scene change real devices and scenes: a live operation needs both dryRun=false and confirmSideEffect=true, the rs property is blocked, and failed writes should not be retried blindly. Device and home data go to Yeelight cloud services.

Installation

In SourceWeft

  1. Open Yeelight IoT MCP Server in the dashboard and add it to a workspace.
  2. Connect Authorization token credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.Yeelight%2Fyeelight-iot-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

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

README

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:

ServerRole in the suiteCore capabilities
Metadata MCPHome understanding and guarded management.Broad discovery and guarded management workflows, multi-region authorization, and request-scoped home selection.
IoT MCPLive 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 needRecommended entry point
First Yeelight MCP integrationConfigure 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 workflowsYeelight Metadata MCP
Multi-region authorization and request-scoped home selectionYeelight Metadata MCP, optionally configured with Yeelight Home
An existing integration that depends on control_node or execute_sceneKeep using Yeelight IoT MCP
Develop or troubleshoot focused direct control, live state, or scene executionUse 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

bash
npm install --global yeelight-homeyeelight-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:

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

Required request header:

text
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

bash
git clone https://github.com/Yeelight/yeelight-iot-mcp.gitcd yeelight-iot-mcp
uv sync --extra testYEELIGHT_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

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

ToolPurposeSide effect
get_currnet_house_infoRead the selected house. The misspelling is retained for compatibility.Read only
get_areasList areas with cursor pagination.Read only
get_roomsList rooms with cursor pagination.Read only
get_devicesList all devices or filter by room.Read only
get_groupsList all groups or filter by room.Read only
get_scenesList scenes with cursor pagination.Read only
control_nodePreview or execute a node property command.Dry-run by default
execute_scenePreview 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:

VariableDefaultPurpose
YEELIGHT_IOT_MCP_API_BASE_URLhttps://api.yeelight.comYeelight API origin
YEELIGHT_IOT_MCP_DEFAULT_REGIONcnFallback Region for opaque tokens
YEELIGHT_IOT_MCP_BIND_HOST127.0.0.1 in local/testBind address; production defaults to 0.0.0.0
YEELIGHT_IOT_MCP_PATH/mcpStreamable HTTP path
YEELIGHT_IOT_MCP_HTTP_TIMEOUT15Upstream timeout in seconds
YEELIGHT_IOT_MCP_FETCH_NODES_MAX_SIZE300Maximum list page size
YEELIGHT_IOT_MCP_NACOS_ENABLEDfalseEnable optional service registration
YEELIGHT_IOT_MCP_LOG_DIR./logs/yeelight-online-iot-mcp-serverLog directory

Test

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

Source: README.md at commit 4d441cd

Tools

0
This server asks for a credential such as an API key, so SourceWeft could not read its tools without one and has not indexed them.

Version history

1
  1. v0.1.0LatestOct 12, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts