Home Assistant MCP 接入 Gemini CLI

💡 无需安装?直接使用 cloud.anythingmcp.com。 登录后,点击 Connectors → Home Assistant,粘贴你的凭据,生成 MCP API 密钥即可。无需 Docker,无需 git clone,无需本地服务器。

Home Assistant + Gemini

让你的 AI 读取 Home Assistant:每个传感器、灯、门和恒温器的当前状态,记录的历史数据,记录事件发生时间的日志,以及你的日历。只读:绝不会控制设备。支持自托管的 Home Assistant。

前提条件

请查看连接器内置的完整设置说明(在应用内商店中选择该连接器即可看到)。此连接器所需的环境变量如下:

HOME_ASSISTANT_URL, HOME_ASSISTANT_TOKEN

第 1 步 — 获取凭据

设置大约需要 3 分钟。你需要一个 AnythingMCP 能够访问的 Home Assistant 实例,以及一个长期访问令牌,最好来自专用的非管理员用户。

1. 将 HOME_ASSISTANT_URL 设置为你打开 Home Assistant 时使用的地址,末尾不带斜杠,也不带 /api,例如 https://home.example.com 或 http://192.168.1.10:8123(默认端口为 8123)。
2. 推荐:在 Settings → People → Users → Add user 下,为 AnythingMCP 创建一个专用的 Home Assistant 用户,并关闭 Administrator。连接器使用的所有端点都不需要管理员权限。
3. 以该用户身份登录,点击左下角你的名字打开个人资料。打开 Security 标签页,在 Long-lived access tokens 下点击 Create token。复制令牌(只显示一次,有效期为 10 年),并将其粘贴到 HOME_ASSISTANT_TOKEN 中,不要带 Bearer 一词。
4. 安装连接器并运行 home_assistant_get_config:它会返回版本、位置名称和时区,并确认地址和令牌可用。

读取内容:每个实体(传感器、灯、空调、门、在家状态)的当前状态及其属性,某段时间内记录的数值历史,记录事件发生时间的日志(例如车库门上次打开的时间),你的日历及其事件,以及实例配置。实体 ID 形如 sensor.living_room_temperature 或 binary_sensor.garage_door。

只读:每个工具都是 GET 请求。连接器无法调用动作(services)、开关任何设备、解锁门、运行脚本或更改状态。Home Assistant 自带的动作端点并非仅限管理员使用,因此这一保证来自连接器只暴露读取操作,而不是来自令牌。

Home Assistant 的运行位置:在自托管的 AnythingMCP 上,位于私有网络中的实例(http://192.168.x.x:8123、homeassistant.local)需要由管理员在 SSRF_ALLOWED_HOSTS 或管理设置的允许列表中放行该主机。AnythingMCP Cloud 只能通过 HTTPS 访问暴露在公网上的实例,例如位于反向代理之后,或使用 Home Assistant Cloud 远程访问。

隐私:家庭数据会显示谁在家以及家庭成员的日常作息。请只将该连接器分配给其用户有权查看这些数据的 MCP 服务器。

时间:时间戳以 UTC 的 ISO 8601 格式传入,并带 Z 后缀,例如 2026-10-01T00:00:00Z。home_assistant_get_config 会返回家庭所在的时区,用于展示结果。

常见错误:401 表示令牌错误或已被删除。针对单个实体或其日历事件返回 404,表示没有该 ID 的实体;每次调用都返回 404,表示 HOME_ASSISTANT_URL 错误,或已经以 /api 结尾。日历事件返回 400,表示 start 或 end 缺失或不是有效的时间戳。连接被拒绝或被阻止,表示该主机不在 SSRF 允许列表中(自托管),或未通过 HTTPS 公开(Cloud)。

该连接器不会调用动作或服务,不会写入或删除状态,不会触发事件,不会渲染模板,不会显示摄像头图像,也不会读取事件流、错误日志或 WebSocket API(区域、设备、实体注册表)。

第 2 步 — 安装适配器

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

第 3 步 — 在 Gemini 中添加连接器

你的服务器 URL： 在 AnythingMCP 中打开 MCP Servers → 此连接器所在的服务器，复制它的 URL（https://cloud.anythingmcp.com/mcp/…）。本指南中出现 YOUR_SERVER_ID 的地方都用它替换。

Gemini CLI 从 ~/.gemini/settings.json（Windows 上为 %USERPROFILE%\.gemini\settings.json）读取 MCP 服务器。添加：

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. 在 AnythingMCP 的 MCP Servers → 你的服务器 → API keys 中创建 MCP API 密钥，并用它替换 YOUR_MCP_API_KEY。
2. 保存文件并重启 gemini。
3. 在 Gemini CLI 中运行 /mcp（或在终端运行 gemini mcp list）— anythingmcp 应显示为已连接。
4. 开始输入提示 — Gemini CLI 现在可以调用 Home Assistant 的工具。

可用工具

常见问题

Gemini CLI 从哪里读取 MCP 服务器？ 用户级配置位于 ~/.gemini/settings.json，项目级配置位于项目内的 .gemini/settings.json。gemini mcp list 会列出每个服务器及其连接状态。

后续步骤

• 连接器介绍页
• 连接到 Claude
• 连接到 ChatGPT