Home Assistant

Home Assistant MCP 服务

通过 AI 助手读取 Home Assistant 的实体、区域、历史记录和日志簿，询问任何模板能够回答的问题，并执行操作：调暗灯光、设置恒温器、运行脚本。只有执行操作会改变任何内容；对于锁、报警面板、遮盖物和阀门的操作，每次运行前都需要你批准。这里的任何操作都不会转移资金。

你需要一台本机可以访问的 Home Assistant（通过网络或远程地址访问），以及一个长期访问令牌。推荐使用非管理员用户的令牌：除了 render_template 外，所有工具都能使用；对于 Home Assistant 仅允许管理员执行的少数操作（重新加载、重启等），服务会自行拒绝，不会向 Home Assistant 发出请求。管理员令牌还可以执行这些操作。无需注册账户，也无需付费。令牌错误会导致登录失败；Home Assistant 可能会在失败几次后封禁某个地址，因此服务绝不会再次发送已被拒绝的令牌。

你可以询问

• “现在有哪些灯亮着？”
• “客厅的温度昨晚发生了什么变化？”
• “今天早上是谁或什么东西解锁了前门？”
• “走廊里有哪些设备？”
• “把厨房的灯调暗到 30%。”
• “锁上前门。”（需要先由你批准）

安装

使用 Claude Code：

claude mcp add home-assistant -e HOME_ASSISTANT_URL="<Home Assistant address>" -e HOME_ASSISTANT_TOKEN_FILE="<path to Long-lived access token file>" -- npx -y @foreverworks/mcp-home-assistant

Claude Desktop（Settings、Developer、Edit Config）和大多数其他客户端都以 JSON 格式读取相同的命令：

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-home-assistant"],
      "env": {
        "HOME_ASSISTANT_URL": "<Home Assistant address>",
        "HOME_ASSISTANT_TOKEN_FILE": "<path to Long-lived access token file>"
      }
    }
  }
}

每种方式都会在 Node 22.19 或更高版本上运行已发布的软件包。VS Code 和 Claude Desktop 安装包会在添加服务时逐项询问设置；可选项可以留空。Cursor 则从环境中读取各项设置（例如 ${env:HOME_ASSISTANT_URL}），因此请在启动 Cursor 前设置这些值。上述命令仅设置必需项；其余设置请参阅配置。

从克隆安装

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add home-assistant -e HOME_ASSISTANT_URL="<Home Assistant address>" -e HOME_ASSISTANT_TOKEN_FILE="<path to Long-lived access token file>" -- node "$PWD/servers/home-assistant/dist/index.js"

在 JSON 配置中，命令为 node，唯一的参数是 servers/home-assistant/dist/index.js 的完整路径。如需通过 HTTP 在多个客户端之间共享同一个运行实例，请参阅 docs/deploying.md。

配置

变量	必填	含义
HOME_ASSISTANT_URL	是	打开 Home Assistant 时使用的地址，例如 http://homeassistant.local:8123 或 https://ha.example.com，不带 /api。对于位于代理之后的实例，会保留路径前缀。
HOME_ASSISTANT_TOKEN_FILE	是	仅包含长期访问令牌的文件（本地运行时，HOME_ASSISTANT_TOKEN 直接填写令牌）。
HOME_ASSISTANT_CONFIRM_DOMAINS	否	需要逐次确认的操作域，以逗号分隔。默认值为 lock,alarm_control_panel,cover,valve；设为 none 则不确认。若值不是域名列表，则会拒绝所有操作，直到修正为止，因此拼写错误不会导致确认机制关闭。

每次调用都会重新读取这些变量，因此修正值会在下一次调用时生效，无需重启。即使未设置这些变量，服务仍会启动并列出其工具，但每个工具都会返回一条指出缺少什么的 config 错误。

如果部署设置了 MCP_EGRESS_ALLOW，则必须允许访问 HOME_ASSISTANT_URL 所在的主机（对于上面的地址，即 homeassistant.local）：服务不会通过 HTTP 或 WebSocket 连接其他任何地址。会关闭私有网络访问的沙盒（systemd 的 IPAddressDeny）必须开放实例的地址（部署文档）。所有服务共用的变量见配置文档。

获取长期访问令牌

1. 在“设置”中的“人员”里为助手创建一个人员账号，允许其登录，并关闭管理员权限；然后以该用户身份登录。这样，日志簿会将其标记为相关操作的执行者，并且该用户可以操作家中实体，但无法更改 Home Assistant 本身。只有在需要 render_template 和仅限管理员使用的操作时，才使用管理员账号：Home Assistant 会用 401 响应其他用户对此类功能的请求，并将其计为登录失败。因此，本服务会识别令牌所属用户，绝不会向其发送此类请求。

2. 打开个人资料（侧边栏底部显示你的姓名），然后选择其中的安全标签页。

3. 在长期访问令牌下，选择创建令牌，填写名称（例如“MCP server”），然后复制令牌。Home Assistant 只会显示一次；除非在此删除，否则令牌有效期为十年。

4. 将令牌单独保存在只有你能读取的文件中，并将 HOME_ASSISTANT_TOKEN_FILE 指向该文件：

   umask 077 && printf '%s\n' '<the token>' > home-assistant-token
   

首次运行

1. 请求 health。正常响应会显示 ok: true、版本、state: RUNNING、时区、websocket: ok、令牌所属用户及其是否为管理员（如果不是管理员，unavailable_tools 会列出 render_template），以及每个域中的实体数量。
2. 询问某个区域内有哪些内容，或哪些灯处于开启状态，以查看 list_areas 和 list_entities 的运行情况，然后尝试对一盏灯执行操作。
3. 如果 health 返回 auth，请先修正令牌，再处理其他问题：参见故障排除。

工具

read 不会更改任何内容；write 会在你的家庭环境中执行操作；每次调用前，都需要由你批准加粗的 write（下文）。

工具	访问权限	功能
health	读取	检查服务是否能与该实例正常工作：版本、状态、时区、WebSocket API 是否已登录，以及各领域的实体数量；出现问题时返回 ok: false。
list_entities	读取	按领域、区域或关键词查找实体：每行显示一个实体的 ID、名称、状态、单位和区域（最多 1,000 个，默认 100 个）。
get_states	读取	获取最多 50 个实体的状态、属性及其上次变更时间。
list_areas	读取	从 Home Assistant 的注册表中获取所有区域（或指定区域），以及其楼层、设备和实体。
history	读取	查看最多 20 个实体在指定时间段内的状态变化（默认最近 24 小时，最长 31 天），并保留最新的变更。
logbook	读取	查看指定时间段内发生的事件，可选指定一个实体，并显示每条记录的触发者：用户、操作或自动化。
list_actions	读取	查看可用操作：每个领域的操作名称，或指定领域的操作及其字段。
render_template	读取	使用实体状态和辅助项渲染 Home Assistant 模板；仅限使用管理员令牌。
call_action	写入	对目标（实体、设备、区域、楼层或标签）执行操作并传入数据，然后返回状态发生变化的实体；逐次调用前要求你批准操作；如果令牌用户不是管理员，则拒绝仅允许管理员执行的操作。
call_action_confirmed	写入	需要你批准调用后，执行任意操作。

确认

对于需要你批准的操作，call_action 会在发送任何内容前拒绝执行，并返回 needs_confirmation：

• 属于 HOME_ASSISTANT_CONFIRM_DOMAINS 之一的操作（lock.unlock、 cover.open_cover、alarm_control_panel.alarm_disarm、valve.open_valve）；
• 针对上述任一领域实体的其他领域操作（例如对 cover.garage_door 执行 homeassistant.toggle）；
• 目标为设备、区域、楼层、标签或 all 的 homeassistant 操作，因为这些操作可能触及上述对象。

这些操作会通过 call_action_confirmed 执行，其确认流程类似支付，但不会发生任何付款：每次调用前，客户端都会询问你（Claude Code 在所有权限模式下都会这样做）。设置 MCP_CONFIRM=elicit 后，服务本身会根据即将执行的调用内容，向你显示一行提示，并要求输入验证码或密码，密码会显示为 ****：

home-assistant: run the Home Assistant action lock.unlock on lock.front_door, with code=****

MCP_MAX_ACCESS=read 会关闭两个操作工具，只保留所有读取工具。各客户端的询问方式请参阅 docs/security.md。

故障排除

auth，状态码 401。 Home Assistant 拒绝了令牌：令牌已删除、其用户已被移除或停用，或者复制时内容不完整。 重新生成一个令牌（见上文），并将其放入令牌文件。在文件中放入另一个令牌或服务重启之前，每次调用都会以 sent: false 返回 auth，且不会发送任何内容，因为 Home Assistant 会将每次拒绝都记录为登录失败，并可能封禁该地址。

auth，状态码 403。 Home Assistant 或其前置代理拒绝了此机器的地址。通常是 Home Assistant 在多次登录失败后封禁了该地址：从 Home Assistant 配置文件夹中的 ip_bans.yaml 移除该地址，重启 Home Assistant，检查令牌，然后重启此服务。

unreachable。 HOME_ASSISTANT_URL 未收到任何响应。检查 Home Assistant 是否正在运行，以及此机器是否能访问它：在这台机器上的浏览器中应能打开同一地址。消息会说明网络返回了什么（ECONNREFUSED：该端口上没有程序在监听；ENOTFOUND：此处无法解析该名称）。

unavailable。 Home Assistant 返回了服务器错误：它正在启动、停止或重启。等待一分钟，然后调用 health。

needs_admin。 令牌所属用户不是管理员，但此操作需要管理员权限：render_template，或 Home Assistant 仅允许管理员执行的操作。如果返回 sent: false，则是服务自行拒绝了请求，且请求未到达 Home Assistant。其他所有工具都可使用此令牌；只有在需要这些操作时才使用管理员令牌。

permission。 令牌有效，但 Home Assistant 返回的 WebSocket 命令仅限管理员使用。此服务的命令都不应需要管理员权限；请连同 health 返回的版本信息一起报告此问题。

needs_confirmation。 该操作需要逐次确认；助手应调用 call_action_confirmed，它会先征求你的确认。

outcome_unknown。 操作已发送，但没有收到明确答复：它可能已经执行。再次运行前，请先查看实体（get_states）。服务绝不会自行重复发送操作。

端点返回 not_found。 history 或 logbook 背后的集成未加载。在 configuration.yaml 中配置 default_config: 会加载这两个集成以及 recorder。

drift。 响应来自 Home Assistant 以外的来源，通常是代理的登录页面。将 HOME_ASSISTANT_URL 指向 Home Assistant 本身，或指向一个会直接转发 /api、且不自行要求登录的代理。

使用 https:// 时出现证书错误。 此服务会像浏览器一样检查证书。对于使用自有证书颁发机构的实例，请通过 NODE_EXTRA_CA_CERTS 将该机构的证书提供给 Node；或者在你信任的网络上使用该实例的 http:// 地址。

工作原理

两种 API。 状态、操作、历史记录、日志簿和模板来自 REST API。区域、楼层、设备和实体注册表仅存在于 WebSocket API，因此 list_areas 和 list_entities 会为此打开一个短暂会话：使用令牌登录，立即发送命令，然后关闭会话。

被拒绝的令牌绝不会再次发送。 Home Assistant 会将每次使用错误令牌的请求记录为登录失败，发出“登录尝试失败”通知；如果启用了 IP 封禁，甚至只需一次失败就可能永久封禁该地址。因此，收到 401 或 403 后会立即返回，绝不重试或续期；服务会根据被拒绝令牌的 SHA-256 值记住它，在令牌文件更改或进程重启前，后续调用都会直接失败，不再发送请求。在令牌首次通过验证之前，请求会逐个发送，因此错误令牌只会造成一次登录失败，而不是每个正在等待工具结果的请求都失败一次。

操作只发送一次。 网络错误或 502、503、504 响应后，读取操作会再试一次。但操作不会重试：超时或服务器错误后，操作可能已经执行，因此结果为 outcome_unknown。对于不存在的操作，以及数据未通过验证的操作，Home Assistant 都会返回同样的普通 400 错误，因此收到 400 后，服务会读取操作列表以确定是哪种情况。

它知道令牌属于谁。 非管理员用户的有效令牌在请求仅允许管理员执行的操作时，同样会收到 401，并被计为登录失败。因此，在首次使用模板或操作之前，服务会通过 WebSocket API 查询令牌所属用户（auth/current_user），并按令牌的 SHA-256 值缓存结果，然后自行拒绝需要管理员权限的请求。需要管理员权限的操作信息来自 Home Assistant 的源码：模板端点、每个 reload 操作，以及大约 50 个集成注册的操作都仅限管理员使用（homeassistant.restart、recorder.purge、所有 hassio 操作等）。如果某个操作此前未知，服务会在 Home Assistant 首次返回 401 时记录它，并针对该令牌记住此操作，之后绝不再发送；令牌仍可继续使用。health 每次都会重新查询，因此能发现后来被提升为管理员的用户。

凭据不会出现在响应中。 摄像头的 access_token 属性会被移除，entity_picture 等代理地址中的 token= 会被替换为 [redacted]，之后状态才会传给模型。

限制

• 它可以读取和执行操作，但不会进行配置：自动化、脚本、场景、仪表板、辅助项、集成和用户仍需在 Home Assistant 自带的界面中管理。
• 不提供实时更新：每次调用都会读取当前状态；不会订阅事件。
• 审批按域进行。解锁门的脚本、场景或自动化会作为 script、scene 或 automation 操作运行：如果你的这些操作会执行此类任务，请将相应域添加到 HOME_ASSISTANT_CONFIRM_DOMAINS。 homeassistant.restart 默认不需要审批；添加 homeassistant 即可审批所有跨域操作，包括重启。
• 每台服务器只能运行一个实例，并使用长期有效的令牌。不会使用 Home Assistant 的 OAuth 登录。
• 如果某个集成在 2026-10-26 之后添加了仅限管理员使用的操作，非管理员令牌首次请求该操作时会导致一次登录失败。对于 Home Assistant 只允许读取而不允许控制的用户，每次对其无权控制的实体执行操作都会收到 401：请为助手提供一个普通用户账号。
• 历史记录和日志簿只能追溯到记录器保留数据的时间范围（除非另行配置，否则为 10 天）。

Home Assistant 的其他服务

检索日期：2026-10-26（Home Assistant 文档、GitHub、PyPI、npm 和网页）。找到：

• Home Assistant 自带的 Model Context Protocol Server 集成（自 2025.2 起）：在 /api/mcp 提供其 Assist API 的工具，通过 OAuth 为客户端登录（默认仅限管理员），并且只能访问已向 Assist 暴露的实体。其文档未提及历史记录、日志簿、注册表或模板。
• ha-mcp（Python）：约 90 个工具，包括自动化、仪表盘、历史记录、跟踪记录和备份；可作为自定义集成、附加组件安装，也可通过令牌作为进程运行。
• hass-mcp（Python）：实体、操作、历史记录、统计数据、错误日志和仪表盘；使用长期有效令牌。
• homeassistant-mcp （TypeScript）：设备控制、附加组件和自动化配置。

这个服务面向希望使用与此处其他服务相同工具包、但功能精简且以读取为主的读者：每个工具都标记为读取或写入，设有 MCP_MAX_ACCESS 和按客户端设置的上限，每次调用都有一条审计记录；逐次审批那些会打开住宅的操作，并显示确切命令；Home Assistant 拒绝过的令牌不会再次发送；出站流量仅允许访问这一个实例。它不会在 Home Assistant 中安装任何东西。