Install MCP Server for Xiaozhi in Home Assistant (HA) via HACS, then add the MCP Server for Xiaozhi integration (the hosts we shipped after April 2026 already have this step configured).
Step 1: Get the Xiaozhi MCP Endpoint Address
The Xiaozhi device needs a communication address to connect to your HA, and this address is obtained in the Xiaozhi cloud console.
- Open and sign in to the official Xiaozhi console in a computer or phone browser (usually xiaozhi.me; if you self-host, open your own console address).
- In the device list, find the ESP Xiaozhi device you are currently using and click Configure.
- Scroll down the page to find the MCP Setting section.
- Click Get MCP Endpoint; a link (usually starting with wss://) will be generated. Copy this address for later use.
Step 2: Configure the Xiaozhi MCP Integration in HA
Now we will enter the address you just copied into HA, so HA can actively connect to the Xiaozhi server.
- Open the Home Assistant panel and click Settings in the left sidebar.
- Click Devices & Services.
- Click Add Integration in the bottom right corner.
- Type MCP or Xiaozhi in the search box, find MCP Server for Xiaozhi and click it.
- Fill in the configuration fields:
- Xiaozhi MCP Endpoint Address: paste the link you copied in step 1.
- Select the required MCP (if an llm_hass_api checkbox appears): be sure to check it. This is the control feature built into HA, and only with it checked can HA delegate the control of your home devices to Xiaozhi. If you have other MCPs in HA, you can check them too.
Click Submit / Done.
Check the status: wait about a minute, then go back to the MCP Setting page in the Xiaozhi console, click Refresh and see whether the status has become Connected.
Step 3: Expose HA Devices to Xiaozhi (Key Step!)
If you just shout Turn on the light to Xiaozhi, it may say it cannot find the device, because for security reasons HA does not expose all devices to voice assistants by default.
- In the HA panel, go to Settings -> Voice assistants.
- Find the Expose tab.
- Here you will see a list of the various devices in your home. Check the devices you want Xiaozhi to control (for example specific lights, switches, air conditioners, fans, temperature and humidity sensors, etc.). For beginners we suggest checking only 1-2 lights for testing at first, and checking the rest after the test succeeds.
Step 4: Voice Testing and Debugging
Once everything is configured, you can start giving commands to Xiaozhi!
- Test control: Xiaozhi, Xiaozhi, turn on the light in the study.
- Test query: Xiaozhi, Xiaozhi, what is the temperature in the living room right now?
How to troubleshoot when problems occur (guide to avoiding pitfalls):
- Xiaozhi does not respond or answers randomly: go to the Xiaozhi cloud console and check the Chat History. See whether Xiaozhi understood you and whether it tried to call the Home Assistant tool (Function Call).
- Command conflicts: currently, if the built-in music/screen control logic is enabled on the Xiaozhi side, it may conflict with HA’s light and music control. If controlling lights often fails, try phrasing the command more specifically, for example Turn on the living room ceiling light through smart home.
- HA logs: if Xiaozhi did send the command but the device does not react, go to Settings -> System -> Logs in HA and check whether the MCP plugin reports any errors.
Following these four steps, your Xiaozhi AI will successfully become a real smart home butler!
