Yeelight IoT MCP Server

What Yeelight IoT MCP Server MCP server does

Yeelight IoT MCP Server provides an MCP interface to Yeelight Pro homes. It covers home and topology discovery, including areas, rooms, devices, groups, and scenes, and exposes current information needed to identify targets before issuing a control request. The service is the focused live-state and control component of Yeelight's cloud MCP suite.

The repository is intended for specialized integrations and development work involving direct control or scene execution. For a first-time setup, the project documentation recommends using the unified Yeelight MCP setup, which configures this service together with Yeelight Metadata MCP.

How it works

The service communicates over Streamable HTTP. Clients can use the hosted endpoint at https://api.yeelight.com/apis/mcp_server/v1/mcp, or operators can run the application locally with Uvicorn and connect through a local /mcp URL. Both deployment modes use Yeelight cloud APIs; local hosting does not provide an offline gateway.

Requests require an Authorization header. The hosted service also accepts optional region and house-selection headers. If those values are omitted, the service can derive the region from the token and select a Pro home according to its documented defaults.

Read tools support cursor pagination where applicable. Control requests are designed as a two-step workflow: identify the current target, generate a dry-run plan, review it, and then submit a confirmed live operation. Yeelight IoT MCP Server requires both dryRun=false and confirmSideEffect=true before a control or scene request can cause changes.

Setup and configuration

Local deployment requires Python 3.10 or newer and uv. The documented workflow clones the repository, installs dependencies with uv sync, sets a local runtime environment, disables Nacos registration, and starts uvicorn on 127.0.0.1:9000.

The hosted configuration needs the MCP URL and an Authorization header. The recommended beginner path uses Yeelight Home to complete QR-based sign-in and configure an MCP client. That setup can provision the Metadata and IoT services together without placing the authorization value directly in the AI client's configuration.

Available local configuration includes the API base URL, fallback region, bind host, MCP path, HTTP timeout, runtime environment, and Nacos registration setting. The service does not read an operator's CLI Profile, and every request must include an explicit Authorization header.

Tools and capabilities

Yeelight IoT MCP Server exposes eight tools:

• get_currnet_house_info reads the selected house. The spelling is intentionally retained for compatibility.
• get_areas, get_rooms, and get_scenes return cursor-paginated collections.
• get_devices lists devices, optionally restricted to a room.
• get_groups lists groups, optionally restricted to a room.
• control_node previews or executes a node property command.
• execute_scene previews or executes a scene.

The first six tools are read-only. The final two default to dry-run behavior and provide redacted control plans before execution. Callers should resolve names to current identifiers and inspect supported properties before attempting a write.

Limitations and notes

A Yeelight Authorization token is required. Region and house ID are optional, but omitting them invokes the service's selection behavior. The rs control property is blocked by the current safety policy. Failed writes or scene executions should not be retried blindly.

The service is specifically focused on live state, topology, device control, and scene execution. Broader workflows such as account management, automations, favorites, maintenance, and other guarded management operations belong to Yeelight Metadata MCP rather than this server.