Read the home overview
Read only the rooms, devices, groups, scenes, and automations in my current default home. Do not change anything.
What you will seeA real home structure summary with zero changes.Connect Yeelight MCP to your AI
Already configured Yeelight Home and using an MCP-compatible AI client? Choose the client in the real setup wizard, connect it, then move from a read-only check to one verifiable lighting response.
- Estimated time
- 16 minutes
- What success looks like
- AI reads your real default home, previews one exact action, then executes it once after confirmation and reads the real state back.
Before you start
- Yeelight Home is installed and runs correctly
- Your Yeelight Pro account is signed in and a default home is selected
- Your AI client supports MCP
- Your account has sufficient access for controls or home changes
First, verify that Yeelight Home is ready
This guide does not reinstall Yeelight Home or repeat home configuration. Run two read-only commands. Continue only when the version is readable and doctor reports `status: ok` with an authenticated account.
If either command fails, finish installation, QR sign-in, and default-home selection in the Yeelight Home guide first.
yeelight-home version --jsonyeelight-home version --json
Interactive demo only. It does not run a command or connect to a device.
yeelight-home doctor --jsonyeelight-home doctor --json
Interactive demo only. It does not run a command or connect to a device.
You are done whenBoth commands run, and doctor reports `status: ok` and `authenticated: true`.
If it did not workIf the command is missing, sign-in is absent, or no default home is selected, complete the Yeelight Home guide first. Never share a QR code, token, cookie, or full doctor output.
Choose the AI client and review the plan
Run the real interactive wizard without `--yes`. It first lists 20 verified MCP clients and lets you choose. It then shows the client, four-step plan, and final confirmation. The default route connects the local Yeelight Home Runtime.
Enter the client number, confirm that the plan says “Connect this computer's Yeelight Home Runtime,” then enter Y. During the account check you can keep the current account or scan again to switch accounts.
yeelight-home setup --lang en-US --mode mcpyeelight-home setup --lang en-US --mode mcp
Interactive demo only. It does not run a command or connect to a device.
This order comes from a real yeelight-home 0.1.25 TTY run. The page compresses the client list horizontally; the terminal prints every client on its own line.
You can also ask AI to guide the setup
Run `yeelight-home setup --lang en-US --mode mcp`. Let me choose which AI client to configure, and show me the final four-step plan exactly before I confirm. During the account check, let me decide whether to keep the current account or scan again. Never send a QR code, token, or home ID into chat. When setup finishes, remind me to fully quit and reopen the AI client I selected.
Read the transcript
A real yeelight-home 0.1.25 run selects Codex and shows runtime, account check, local MCP configuration, and read-only verification. The demonstration cancels at the final confirmation, so no client configuration changes.
The wizard may scan again to switch accounts. Do not force it to skip the account check just because an account is already signed in.
You are done whensetup finishes client configuration and read-only home verification, then asks you to restart the selected AI client.
If it did not workEnter n at the final plan to stop; the terminal confirms that setup was canceled with no configuration changes. Choose a client manually when auto-detection does not match your intent. Do not use `--agent auto --yes` to skip beginner-facing choices and confirmation.
Restart the AI, then run the first read-only check
Fully quit and reopen the AI client you configured. The first request reads only the default home name and room and device overview. It does not control devices or change the home.
Check whether Yeelight MCP is available
Check whether Yeelight MCP is connected. Read only my current default Yeelight home name and the room and device counts. Do not control devices or change settings. If it fails, tell me whether the problem is the connection, sign-in, default home, or tool loading.
Read-only verification with zero changes. Sanitized interactive demo. It does not read your home or control a device.
You are done whenThe AI returns your real home name and counts and confirms that it changed nothing.
If it did not workFully restart the client if the tool list is empty, then inspect the MCP configuration. A 401 usually requires signing in again with the correct region; an empty result with a healthy connection usually means the default home is wrong.
Experience 1: let AI understand your home
Ask AI to read rooms, devices, groups, scenes, and automations, then flag duplicate names, default rooms, and unassigned devices.
Build a home map
Read only my current default Yeelight home. Build a plain-language map of rooms, devices, groups, scenes, and automations, then flag duplicate names, default rooms, and unassigned devices. Do not change anything yet.
Read-only check with no structural changes. Sanitized interactive demo. It does not read your home or control a device.
Read the transcript
The user requests a read-only summary of the current home. AI reads rooms, groups, scenes, and automations and reports zero changes. The visual demonstrates the interaction shape and contains no real home data.
You are done whenThe AI returns a map that matches your home and practical organization suggestions.
If it did not workRun `yeelight-home home select` when the response belongs to the wrong home. For duplicate names, ask AI to expand rooms, positions, and candidates instead of guessing.
Experience 2: read one light's real state
Read before control to avoid duplicate actions and the wrong target. Name the room, position, and device, and request only properties the device actually supports.
Read one exact light
Read the power and brightness of the spotlight to the left of the living-room TV wall. Include color temperature if it supports that property. Read only; do not adjust it. List candidates instead of choosing when the target is not unique.
Read-only state query. Sanitized interactive demo. It does not read your home or control a device.
You are done whenThe AI returns the exact device's real state and confirms that it sent no control.
If it did not workAdd left/right, bedside, or TV-wall position when the candidate is ambiguous. Accept the device's real capabilities instead of asking AI to invent unsupported values.
Experience 3: preview one lighting change
Ask AI to name the unique target, real current state, and planned change, then wait for confirmation. The light should not change at this point.
Preview the living-room floor lamp
I want the floor lamp beside the living-room sofa at 40% brightness. First confirm which light you found, read its real current brightness, and describe the planned change. Do not execute yet.
No control is sent before confirmation. Sanitized interactive demo. It does not read your home or control a device.
Read the transcript
The demonstration resolves the floor lamp by room and position, keeps the current value tied to a live read, sets the plan to 40%, and stops for confirmation without controlling the device.
Continue only after both the target and change are correct.
You are done whenThe AI shows one target, its real current state, the planned change, and a waiting-for-confirmation state.
If it did not workAdd room, position, or nickname when the target is ambiguous. Stop when the device is offline or does not support brightness; do not substitute a similar device.
Experience 4: inspect a scene's real impact
A scene may change several devices. Confirm the home, scene name, affected targets, and expected result before execution.
Preview the living-room Movie scene
Find the living-room Movie scene in my current default home. Tell me which devices it affects and the expected result, but do not run it. List candidates first if there are duplicate scene names.
The multi-device scene has not run. Sanitized interactive demo. It does not read your home or control a device.
Always review the scope of a multi-device action.
You are done whenThe AI explains the real impact and waits for your confirmation.
If it did not workAsk AI to list scenes when the named scene does not exist. Add the room when names collide. Use an account with sufficient access instead of bypassing permissions.
Experience 5: execute once, then read back
Continue only when the target and plan are correct. Reuse the unique target, send one control, then read the real state again.
Confirm the single-light adjustment
I confirm the previous change to the floor lamp beside the living-room sofa: set brightness to 40%. Execute once only, then read that light again and tell me whether it took effect. If the result is uncertain, do not control it again; explain the problem.
Stop on an uncertain result; do not retry blindly. Sanitized interactive demo. It does not read your home or control a device.
Confirm only the target and change you just previewed.
You are done whenThe AI reports one execution and proves success or failure with the real post-control state.
If it did not workCheck online state, property support, and account permissions when the state does not change. Stop on a mismatched readback instead of retrying repeatedly.
Default local route and cloud compatibility route
Most people should run `yeelight-home setup --lang en-US --mode mcp`. Its default `mcpSource` is `local`, and the AI client starts `yeelight-home mcp serve --stdio` from its configuration. Add `--mcp-source cloud` only when you explicitly need the lightweight hosted compatibility route. A local proxy then reads credentials at request time and connects Metadata MCP and IoT MCP, which access the Yeelight PRO cloud directly rather than using the local Runtime as their execution foundation. Direct gateway access belongs to the LAN route, not this guide.
Try these everyday scenarios first
Start with three to five easy examples. Every sentence is ready to send to your AI.
Read one exact light
Read the power, brightness, and supported properties of the spotlight left of the living-room TV wall. Do not adjust it.
What you will seeLive properties for one exact device.Preview one brightness change
Preview setting the spotlight to the right of the primary-bedroom bed to 30%. Read the current value and wait for confirmation.
What you will seeThe target, real current value, planned value, and confirmation state.Preview an existing scene
Find the living-room Movie scene, describe its real impact, and wait for my confirmation without running it.
What you will seeThe scene's affected targets and expected result.Execute once and read back
Execute the single-light change I just confirmed once, then read it back. Stop if the result is uncertain.
What you will seeOne write followed by a real state readback.More complete scenarios
Inspect group members
Read every position and state in the children's-room downlight group and flag offline or inconsistent members.
What you will seeGroup membership and per-position state.Preview whole-group dimming
Confirm every member of the children's-room downlight group, then preview setting the entire group to 55%. Do not control only one light.
What you will seeComplete membership and a group-wide preview.Find duplicate names
Read only and find duplicate device, scene, and automation names across the home, grouped by room.
What you will seeAn ambiguity list with rooms and entity types.Find offline devices
Read only and list offline devices in the current home by room and last visible state. Do not try to control them.
What you will seeOffline devices and a diagnostic order.Audit automations
Read automation triggers, actions, and enabled states. Find conflicts, duplicates, or invalid rules without changing anything.
What you will seeAutomation issues ordered by priority.Compare scene impact
Compare the affected devices and target states of the living-room Movie and All On scenes without running either.
What you will seeDifferences between two real scenes.Plan home cleanup
Use the real room, device, and group structure to suggest cleanup. Give me a plan without renaming or moving anything.
What you will seeA zero-write organization plan.Preview a rename
Preview renaming the spotlight to the right of the primary-bedroom bed to “Primary right reading light.” Confirm the unique target and impact first.
What you will seeA rename target and impact preview.Preview a new scene
Use the current real devices to preview an Evening Reading scene. List every action and do not create it yet.
What you will seeA reviewable scene action plan.Check access boundaries
Read only and tell me what the current account can view and modify in this home. Do not write anything.
What you will seeAvailable capabilities and restricted actions.Diagnose without retrying
Inspect the control that did not confirm success. Read device state and online status without sending the control again.
What you will seeFailure clues with zero retries.Troubleshooting
Why must I install Yeelight Home first?
The default MCP route lets the AI client start `yeelight-home mcp serve --stdio`. Completing Yeelight Home installation, sign-in, and default-home selection provides the local Runtime and account context MCP needs.
Do I need to upgrade Yeelight Home first?
Run `yeelight-home version --json`, then `npm view yeelight-home version` to inspect the latest npm release. During this guide's verification, the local and npm versions were both 0.1.25, so no unnecessary reinstall was performed.
Is Yeelight MCP one project or two?
The guide presents one Yeelight MCP concept. The default local route configures the Yeelight Home Runtime only. The advanced cloud route connects Metadata MCP and IoT MCP together, so ordinary users do not install or reason about them separately.
What is the difference between local and cloud?
With no `--mcp-source`, setup defaults to `local` and reuses Yeelight Home's full local semantic layer. `cloud` is the lightweight hosted compatibility route. Beginners should prefer the default local route.
Do I need to start an MCP server myself?
Usually no. After setup and a full AI-client restart, the client starts the local stdio service from its configuration. Do not keep a separate terminal process running.
Why does setup ask me to choose an AI client?
Clients use different MCP configuration files and adapters. The wizard lists 20 verified clients and lets you choose the exact target instead of writing to software you do not use.
Why not use `--agent auto --yes`?
Those flags fit a known unattended environment. Beginners should see client selection, account review, and the final plan, so this guide keeps the interaction and confirmation.
Why does setup check the account when I am already signed in?
You may be running setup specifically to switch accounts. The interactive flow lets you keep the current account or scan again; it should not skip the check unconditionally.
What if the QR expires or the account region is wrong?
Run setup again, or use `yeelight-home auth login --qr --region cn` for Mainland China. Singapore, United States, and Europe accounts use `sg`, `us`, and `eu`. Never forward the QR code or scan result.
How do I choose among several homes?
Run `yeelight-home home select`, then choose by number or full name in the terminal. Name the home in conversation too when several homes contain rooms with the same name.
Why are no Yeelight tools visible after setup?
Fully quit and reopen the AI client instead of closing only the conversation. If tools remain empty, rerun setup, confirm the correct client, and inspect the MCP configuration path that client actually reads.
What if my AI client is unsupported?
setup writes configuration only through verified adapters. An unknown client fails clearly instead of reporting false success. Choose a supported client from the list; a new client requires its own adapter.
What if an existing MCP config is empty or invalid JSON?
Back up the client config, repair the empty file to valid JSON, then rerun setup. Do not delete the whole configuration directory because it may contain other MCP entries.
What should I do after a 401, expired sign-in, or empty home list?
Confirm the account region, scan again, then run `yeelight-home doctor --json`. If sign-in is healthy but the home list is empty, confirm that the account has a Yeelight Pro home and the default home is selected.
Why did AI find several lights with the same name?
Homes often contain many downlights or spotlights with identical names. Add the home, room, left/right position, or nickname. List candidates without executing until one target is unique.
Why do writes require confirmation or administrator access?
Control, rename, move, scene, and automation changes have different impact. Preview and confirm first. Use a home administrator when structural changes require it instead of bypassing access checks.
What if the state does not change after control?
Check online state, property support, and readback consistency. Stop when the result is uncertain; repeated sends during network delay may duplicate the action.
Does this guide cover gateway LAN MCP?
No. `--mode lan --mcp-source gateway` is a direct-gateway compatibility route that also requires a gateway address and LAN conditions. This page covers the ordinary Yeelight MCP route.
Keep exploring with the community
Get practical setup help, exchange ideas, and follow what is next for Yeelight AI.
WhatsApp
Yeelight AI Community
Meet other Yeelight AI users and get help with your setup.
Scan with WhatsApp or open the group directly.