mcp_ha_xiaozhi

小智官方服务器(虾哥)对接home assistant的mcp server

原理

使用小智官方给的示例代码，结合mcp_proxy,实现小智官方服务器和home assistant的mcp server打通

参数

XIAOZHI_MCP_ENDPOINT：你的小智 MCP 接入点 HA_MCP_ENDPOINT：你的 HA MCP SERVER 地址 API_ACCESS_TOKEN：你的长效 API 令牌 MCP_TRANSPORT：auto、sse 或 streamablehttp，默认 auto

1. 小智 MCP 接入点： 登录小智官方服务器即可获取。

2. HA MCP SERVER 地址： 可以使用旧版官方 SSE 地址，也可以使用新版 HA-MCP 的 Streamable HTTP 地址。

   • 点击此链接：Home Assistant MCP Server 集成直达安装

   • 或 在 Home Assistant 中，前往 设置 > 设备和服务 > 添加集成。

   • 从列表中选择“模型上下文协议服务器”，并按照屏幕上的说明完成设置。

   • 使用新版 HA-MCP 时，填写设置页面生成的 /private_xxx 连接地址，并确保地址末尾没有空格。

3. 长效 API 令牌： 用于授权访问你的 Home Assistant 实例。

   • 访问你的 Home Assistant 账户配置文件设置，进入“安全”选项卡。

   • 创建长期访问令牌。

1.1.0 代理式工具路由

本版本不再把全部 HA 工具压缩后直接发布给小智，也不需要额外的大模型。 桥接器缓存 HA-MCP 的完整工具目录，只向小智后台的模型提供三个循环工具：

• ha_discover：根据用户目标发现相关工具和推荐执行流程。

• ha_get_tool_help：按需读取一个真实 HA 工具的完整参数结构。

• ha_execute：执行真实 HA 工具，并把结果交回小智模型继续判断。

复杂任务采用“发现 → 查看参数 → 执行 → 根据结果继续”的循环。例如搜索歌曲时， 桥接器会明确引导模型依次查询 music_assistant 服务、获取集成配置条目，最后调用 music_assistant.search，避免把歌曲搜索误判为普通 HA 实体搜索。

启动成功后，日志应出现：

Agentic tool router ready: 78 HA tools cached, exposing 3 loop tools to XiaoZhi

小智执行任务时，还会依次出现 Capability discovery、Serving full help 和 Agent loop executing HA tool。这表示后台模型正在持续使用同一组工具结果完成多步任务。

docker运行

docker run -d --name mcp_ha_xiaozhi \
-e XIAOZHI_MCP_ENDPOINT="你的小智MCP接入点" \
-e HA_MCP_ENDPOINT="你的HA MCP SERVER地址" \
-e API_ACCESS_TOKEN="你的长时效API令牌" \
-e MCP_TRANSPORT=auto \
shawn68/mcp_ha_xiaozhi

https://hub.docker.com/r/shawn68/mcp_ha_xiaozhi/

新版 HA-MCP 配置示例

新版 HA-MCP 的连接地址通常是设置页面生成的私密地址，使用 Streamable HTTP：

docker run -d --name mcp_ha_xiaozhi \
  -e XIAOZHI_MCP_ENDPOINT="你的小智 MCP 接入点" \
  -e HA_MCP_ENDPOINT="http://192.168.1.8:9584/private_xxx" \
  -e MCP_TRANSPORT=streamablehttp \
  -e API_ACCESS_TOKEN="你的长期访问令牌" \
  mcp_ha_xiaozhi:local

HA_MCP_ENDPOINT 末尾不要有空格。使用 /private_xxx 私密地址时，完整地址本身就是凭据，请不要公开。

作为 Home Assistant 自定义应用安装

1. 在 Home Assistant 的应用商店中添加本仓库地址： https://github.com/soonnn1/mcp_ha_xiaozhi-custom

2. 找到“小智 MCP Server（新版）”并安装。

3. 在配置中填写小智 MCP 地址和 HA-MCP 私密地址。

4. MCP_TRANSPORT 选择 streamablehttp，然后启动应用。