Ha MCP For Xiaozhi

What ha-mcp-for-xiaozhi MCP server does

ha-mcp-for-xiaozhi MCP server adds a Home Assistant integration for connecting Xiaozhi AI to Home Assistant through Xiaozhi's official server. Home Assistant acts as the MCP server and sends the selected capabilities directly over WebSocket, without a separate relay described in the project documentation.

The integration can combine Home Assistant's built-in control API with MCP servers that the user has already configured in Home Assistant. These API groups can be selected for an entity, and more than one entity can be configured at the same time. This makes the integration suitable for exposing Home Assistant controls and selected external MCP capabilities to Xiaozhi from one configuration point.

How it works

After configuration, the integration uses the Xiaozhi MCP endpoint supplied by the user. The selected Home Assistant API groups are made available to Xiaozhi. The available tools depend on which entities are exposed to the Home Assistant voice assistant, so the resulting tool set is determined by the entity types and the current Home Assistant version.

Home Assistant's built-in Assist functions are represented by the Assist option in the llm_hass_api selection. Other options correspond to MCP servers connected within Home Assistant and can be proxied to Xiaozhi. The repository also documents a television-control example implemented with a custom Home Assistant script.

Setup and configuration

Install HACS in Home Assistant before installing the integration. In HACS, search for xiaozhi or ha-mcp-for-xiaozhi, download the plugin, and restart Home Assistant.

Then open Settings > Devices & services > Add integration, search for “Mcp,” and select “MCP Server for Xiaozhi.” Enter the Xiaozhi MCP endpoint address and choose the MCP API groups to expose. The configuration includes the built-in Assist functions and any other MCP servers available through Home Assistant.

Once setup is complete, wait about one minute and refresh the Xiaozhi endpoint page to check its status. The ha-mcp-for-xiaozhi MCP server does not document environment variables or a standalone command-line installation method; its documented installation path is the Home Assistant HACS integration.

Tools and capabilities

The ha-mcp-for-xiaozhi MCP server supports:

• Direct WebSocket communication between Home Assistant and Xiaozhi's official server.
• Selection of Home Assistant's built-in Assist control functions.
• Proxying of MCP servers configured in Home Assistant.
• Multiple API groups assigned to one entity.
• Configuration of multiple entities.
• Tools based on the Home Assistant entities exposed to the voice assistant.

Limitations and notes

Use a current Home Assistant release when possible. The project notes that different Home Assistant versions can expose noticeably different tools, including differences between March and May releases.

For unexpected behavior, first inspect Xiaozhi's conversation history to determine how it interpreted the request and whether it called a Home Assistant tool. The documentation identifies possible conflicts between light or music control and Xiaozhi's built-in screen or music controls. If a Home Assistant function was called correctly, enable this integration's debug logging to inspect execution details.