ha -for-xiaozhi

Homeassistant MCP server for 小智AI

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio c1pher-cn-ha-mcp-for-xiaozhi python -m ha_mcp_for_xiaozhi \
  --env HA_MCP_API_KEY="用于认证的 APIKey（如有需要）" \
  --env HA_MCP_ENDPOINT="Xiaozhi MCP 接入点地址"

How to use

This MCP server turns Home Assistant into an MCP server that directly interfaces with Xiaozhi's official MCP endpoint via a websocket connection. It allows you to expose Home Assistant entities and select multiple API groups (both the built-in Home Assistant control APIs and user-configured MCP servers) to be proxied to Xiaozhi in a single entity. You can run multiple MCP configurations or entities, enabling flexible routing to Xiaozhi depending on your use case. The integration emphasizes direct, low-latency communication with Xiaozhi without intermediary proxies, and supports coordinating multiple MCP sources from within a single entity.

How to install

Prerequisites:

Home Assistant is installed and running.
Access to HACS (Home Assistant Community Store).

Install steps:

In Home Assistant, install HACS if you haven't already.
In HACS, search for ha-mcp-for-xiaozhi and install the integration.
Restart Home Assistant when prompted.
After restart, open Home Assistant and add the MCP integration:
- Go to Settings > Devices & Services > Add Integration.
- Search for MCP or Xiaozhi MCp integration (ha-mcp-for-xiaozhi).
- Enter the Xiaozhi MCP endpoint URL and any required authentication details.
Save the configuration and wait a moment. The status should reflect connectivity to Xiaozhi.

Additional notes

Tips and issues:

Ensure the Xiaozhi MCP endpoint URL is reachable from your Home Assistant network.
If using API keys or tokens, keep them secure and do not expose them in logs.
You can expose multiple Home Assistant entities or groups to Xiaozhi; this enables centralized control through Xiaozhi while leveraging existing Home Assistant automations and scripts.
If you encounter connection issues, check the debugging logs in the integration and verify Xiaozhi's endpoint accessibility.
This MCP server is designed to work with the Xiaozhi ecosystem via websocket; keep your Home Assistant and integration version up to date to avoid compatibility issues.