MCP Integrations: Server-Side and Smart Home
MCP sits in two different places in the XiaoZhi ecosystem: device-side tools (built into the firmware — volume, screen, camera; see the MCP Usage Guide) and server-side integration (letting the LLM call external tools). This page collects the community routes for server-side integration; the message format is maintained only in the MCP protocol spec.
Versions and verification status (observed 2026-11-08): route 1 (Endpoint) has passed this site’s local integration rehearsal (see Status below); routes 2 and 3 remain author-claim level, untested. A local rehearsal is not an end-to-end acceptance with real devices/servers.
Route 1: MCP Endpoint registry
| Item | Content |
|---|---|
| Project | xinnan-tech/mcp-endpoint-server (MIT, latest v0.0.7 / commit 0f9302f3, 2026-06-02) |
| Role | Standalone registry: MCP servers register with it; the XiaoZhi server discovers tools through it |
| Who connects whom | MCP tool services → registry ← XiaoZhi server |
| Transport | WebSocket registration and forwarding (author claim) |
| Backends | Designed for xinnan-style custom MCP registration; not a general MCP Registry, not all standard transports |
| Deployment | Docker recommended by the author; FastAPI |
| Status | Local integration rehearsal passed by this site (2026-11-08, v0.0.7): register (MCP-side WebSocket join) → forward (robot-side tools/list rewritten-id forwarded to MCP side) → return (reply with the rewritten id; robot receives aggregated result with total_servers/responded_servers) → revoke (auto-unregister on both-side disconnect) → recovery (re-register after reconnect); negative: invalid token rejected with close code 1008. Health /mcp_endpoint/health?key=… returns JSON-RPC ok. Not verified: end-to-end with the xiaozhi server or real devices |
Route 2: Home Assistant as the MCP server (direct)
| Item | Content |
|---|---|
| Project | c1pher-cn/ha-mcp-for-xiaozhi (MIT, latest v0.2.1 / commit 64cc1507, 2026-10-17) |
| Role | HA integration: HA itself acts as the MCP server, proxying its entities/tools to XiaoZhi |
| Who connects whom | HA → the XiaoZhi-side MCP endpoint: HA connects out via WebSocket to the XiaoZhi MCP endpoint address (v0.2.1 README lines 27/67), no relay |
| Transport | WebSocket (initiated by HA) toward the XiaoZhi-side MCP endpoint (e.g. the xinnan Endpoint service) |
| Permissions | The endpoint address is entered in the HA integration config; HA’s built-in Assist API and other MCP servers configured in HA can be selected |
| Status | Unverified: tool discovery and calls per the author README |
Route 3: Home Assistant MCP Server bridge
| Item | Content |
|---|---|
| Project | mac8005/xiaozhi-mcp-ha (MIT, latest v0.0.27 / commit a6d3ca4a, 2026-10-21) |
| Role | Bridge/proxy between the XiaoZhi cloud service and the local HA MCP Server integration (v0.0.27 README “How it Works”: device ↔ XiaoZhi cloud ↔ this integration ↔ HA MCP Server ↔ HA entities) |
| Who connects whom | This integration initiates and maintains the long-lived WebSocket to the XiaoZhi cloud endpoint (the full URL embeds the token; README: automatic reconnection with exponential backoff); the cloud then sends MCP requests over that established connection, and the integration forwards them to the local HA MCP Server via SSE (http://localhost:8123/mcp_server/sse, legacy HTTP/SSE). Cloud-sent requests ride on the bridge’s own outbound connection — the cloud does not dial into the home network |
| Config & permissions | Two separate tokens: the XiaoZhi-side MCP endpoint URL (with ?token=… from the official console’s MCP page) + an HA long-lived access token (created in the HA profile); never mix them |
| Status | Unverified: modern Streamable HTTP compatibility untested; since v0.0.26 TLS is required outside loopback and message payloads/endpoint URLs are no longer logged — existing LAN plaintext URLs need migration (author CHANGELOG/SECURITY statements) |
Choosing and limits
- The two HA routes are not merged into one procedure: direct and bridged transports and permission models differ;
- Tokens and endpoints live only in server configuration; this page contains no real credentials;
- Compatibility follows each project’s documentation; “unverified” entries get test records once a runtime is available;
- Device-side MCP tools (a different place than these three routes): usage guide.
Linked project records
The three projects, their licenses and observation watermarks are recorded in Ecosystem and the source registry (numeric repo IDs keep identity across renames).