homeassistant-ai / ha-mcp
本文目录
重大变更（v7.3.0）： ha_config_set_yaml 已移至 beta。
HA-MCP——用 AI 管理 Home Assistant#
用 Claude、ChatGPT 和其他 AI 助手配置和自动化 Home Assistant。
🚀 快速开始#
运行 ha-mcp 的推荐方式是 HA-MCP 集成。它通过 HACS（Home Assistant Community Store；在 Home Assistant 2026.11+ 上则是内置市场）安装到 Home Assistant，在进程内运行完整服务器，并适用于所有 Home Assistant 安装类型——Home Assistant OS、Supervised、Container 和 Core——功能完全一致。在所有情况下它都是最简单的设置：安装过程会要求提供管理员访问令牌，并选择客户端可以如何连接。
通过 HACS，或在 Home Assistant 2026.11+ 上通过市场（首选安装方式）将它添加到 Home Assistant：
快速开始：
以下设置适用于 9.0.0 版（2026 年 10 月 28 日）及更高版本；更早版本显示的是更短的设置表单，没有管理员账户步骤。
- 安装 HA-MCP 集成（需要 Home Assistant 2026.8.0 或更新版本；参见兼容性详情）。在 Home Assistant 2026.8–2026.10 上，打开 HACS，搜索 HA-MCP，然后点击 Download。在 Home Assistant 2026.11 或更新版本上，打开 Settings → Marketplace，接受首次运行警告，搜索 HA-MCP，然后点击 Install。HA-MCP 位于默认目录中，因此安装它并接收其更新无需连接 GitHub 或添加自定义仓库。上方的徽章也会打开它的目录页面。已经从更早的 homeassistant-ai/ha-mcp-integration 仓库安装过？它仍会收到相同的发行版。在市场里，请保持 GitHub 连接，以便对该自定义仓库进行后台检查。较旧的已安装版本可能仍显示为 HA-MCP Custom Component；搜索 HA-MCP 会同时匹配两个名称。
- 重启 Home Assistant。
- 决定服务器以哪个管理员账户身份运行。可以在你自己的账户上创建一个长期访问令牌（你的个人资料 → Security → Long-lived access tokens → Create token；它一旦泄露，在任何地方都能用，而且服务器的更改会显示在你的名下）；或者更安全地，在 Settings → People → Add person 下创建一个专供 HA-MCP 使用的账户，开启 Allow login、Local access only 和 Administrator。第二种方案绝不要使用你自己的登录。
- 转到 Settings → Devices & Services → Add Integration，搜索 HA-MCP 并选择 HA-MCP Server。粘贴你的令牌，或者输入你为 HA-MCP 创建的账户的用户名和密码（HA-MCP 会创建自己的令牌），选择客户端可以如何连接——通过 Home Assistant 远程访问（从 Secret URL 开始，这是最简单的；Home Assistant 登录会增加一个登录步骤）和/或网络访问：Local network——然后点击 Submit。两者默认都是禁用的，因此另一台设备上的客户端需要启用其中之一。
- 从条目的 Configure 屏幕复制连接 URL（Settings → Devices & Services → "HA-MCP — Manage Home Assistant with AI" → HA-MCP Server → Configure）。一条通知会确认服务器已启动，并指向那里。
- 把该 URL 粘贴到你的 AI 客户端——完成。
连接 URL。 Configure 屏幕会为远程客户端提供一个 Home Assistant webhook URL——https://<your-ha-domain>/api/webhook/<webhook-id>，通过 Nabu Casa 或任何已指向 Home Assistant 的反向代理（本地则为 http://<ha-host>:8123/api/webhook/<webhook-id>）。对于同一网络上的客户端，服务器也可以直接通过 http://<ha-ip>:9584/private_<random> 访问。
替代其他安装方式： 进程内服务器是一个完整、独立的 ha-mcp 安装——它取代应用（add-on）、Docker 和 uvx/PyPI（stdio）方式。只运行一种；不要将进程内服务器与另一种安装同时运行。
仅本地？ 在设置时保持远程访问禁用（或在条目选项中关闭 Remote access via webhook）——这样根本不会注册 webhook，而直接端口和侧边栏面板仍然可用。
设置面板： 服务器运行时，Home Assistant 侧边栏会出现一个仅管理员可见的 HA-MCP 面板，用于管理工具、功能标志、备份和主题。
可选身份验证： 将 Authentication mode 设为 ha_auth，要求 Home Assistant 账户登录，而不是使用秘密 URL 作为凭据。
手动安装（无 HACS 或市场）： 将此仓库中的 custom_components/ha_mcp_tools/ 复制到你的 Home Assistant config/custom_components/ 目录，然后重启并按上述步骤添加集成。
组件的第二种条目类型——File & YAML services 条目（HA-MCP File & YAML Tools）——仅在你启用 ha-mcp 的可选文件和 YAML 编辑工具（功能标志，默认关闭）时才需要——否则跳过它；以后随时可以添加。它适用于任何服务器类型（进程内、应用、Docker 或 stdio）。
完整的进程内服务器文档 → · 面向特定客户端配置的设置向导 →
🏠 Home Assistant 应用（add-on）#
更愿意把 ha-mcp 作为 Home Assistant 应用（add-on）运行？在 Home Assistant OS 和 Supervised 安装上，这是紧随其后的第二选择——无需管理访问令牌，并且适用于 Claude Desktop、Claude.ai、ChatGPT 以及本地网络上的任何其他 MCP 客户端，或已配置远程访问的客户端。
将仓库添加到你的 Home Assistant 实例：
如果它打开 App store 却没有出现 add-repository 对话框（一个已知的 Home Assistant 问题），请手动添加：Settings → Apps → Install app → ⋮ → Repositories，然后粘贴 https://github.com/homeassistant-ai/ha-mcp。
从 Settings → Apps → Install app 安装 "Home Assistant MCP Server" 并点击 Start。（Home Assistant 2026.2 将 "Add-ons" 重命名为 "Apps"；在旧版本中这是 Add-on store。）
打开 Logs 标签页，找到你唯一的 MCP URL。
将你的 AI 客户端连接到该 URL——无需令牌或凭据设置。
完整的应用文档 →
⚠️ 每个客户端只配置一种安装方式。 自定义组件、应用、Docker/PyPI 和本地 stdio 是运行同一服务器的独立方式——选择一种，并让你的 AI 客户端指向那个单一 URL。在一个客户端中为同一服务器保留两个条目（例如一个本地 uvx ha-mcp@latest 条目带有 HOMEASSISTANT_URL / HOMEASSISTANT_TOKEN，同时又有应用或组件 URL）是连接挂起的已知原因。
其他安装方式#
这些方式在 Home Assistant 之外运行服务器——适用于 Container / Core 安装（无法运行应用）或单独的主机。设置向导会为每种方式生成确切的客户端配置。
- Docker（HTTP 服务器）：以 HTTP 模式运行
ghcr.io/homeassistant-ai/ha-mcp，指向你的 Home Assistant URL 和长期令牌（推荐管理员令牌；非管理员令牌可用但有限制），并将客户端连接到它的秘密 URL。完整命令和各客户端配置见设置向导。 - PyPI / uvx（HTTP 服务器）：用
uvx ha-mcp@latest（或 pip）运行已发布的 ha-mcp 包，作为可流式 HTTP 服务器，方式相同。详情见设置向导。 - 本地 stdio（不推荐）：在你自己的机器上通过 stdio 运行 ha-mcp。下面 Demo server 部分的一键安装器使用此路径；设置向导涵盖将其连接到你自己 Home Assistant 的方法。
- OIDC 身份验证：将远程访问置于外部身份提供方（Authentik、Keycloak、Auth0 等）之后，而不是使用秘密 URL——所有已认证用户共享服务器的 Home Assistant 凭据。参见 OIDC Mode。
⚠️ stdio 存在已知传输问题。 stdio 传输有连接问题，而可流式 HTTP 没有（#1713）。只建议用于演示/测试折腾——真实设置请使用自定义组件或上述 HTTP 方式。
🌐 远程访问（Nabu Casa / Webhook Proxy 应用 / OpenAI Tunnel）#
使用 HA-MCP 自定义组件？你不需要 Webhook Proxy——该组件有自己的内置 webhook 用于远程访问（见顶部快速开始的说明）。代理是给应用用的（它也可以通过 mcp_server_url 选项前置另一个外部服务器）。下面的 OpenAI Tunnel 不同：当 Home Assistant 完全无法公开访问时（没有 Nabu Casa 或反向代理），它适用于任何安装方式。
已经有 Nabu Casa 或另一个指向 Home Assistant 的反向代理？Webhook Proxy 应用会通过你现有的设置路由 MCP 流量——无需单独的隧道或端口转发。
- 从同一商店安装 MCP Server 应用（见上）和 Webhook Proxy 应用
- 启动 webhook 代理，并在提示时重启 Home Assistant
- 从应用日志复制 webhook URL：
MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx- 用该 URL 配置你的 AI 客户端
其他远程访问方式（Cloudflare Tunnel、自定义反向代理）请参见设置向导。
防火墙后的 ChatGPT / Codex（OpenAI Tunnel）。 ChatGPT 连接器通常需要可公开访问的 URL。如果你不能（或不想）暴露一个 URL，由 @norpol 开发的社区版 OpenAI Tunnel for HA-MCP integration 会在 Home Assistant 内运行 OpenAI 的 tunnel-client，通过仅出站连接把你的本地 MCP 服务器 URL 连接到 OpenAI 托管的隧道——无需端口转发、反向代理或公共 URL。将它指向你的 ha-mcp URL，然后把 ChatGPT 连接器附加到同一个隧道 ID。参见 FAQ 条目和 #1811。
Webhook 代理文档 →
🧪 演示服务器（Windows / macOS / Linux）#
想在连接自己的 Home Assistant 之前试用 ha-mcp？无需付费订阅。这些一键脚本会建立到托管演示环境的本地 stdio 连接，让你几分钟内看到它工作。每个脚本中的“连接你自己的 Home Assistant”链接会说明如何指向你的实例。
🍎 macOS#
- 前往 claude.ai 并登录（或创建一个免费账户）
- 打开 Terminal 并运行：
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh- 下载 Claude Desktop（或重启：Claude 菜单 → Quit）
- 问 Claude：“你能看到我的 Home Assistant 吗？”
- 你现在已连接到演示环境！连接你自己的 Home Assistant →
🐧 Linux#
Anthropic 不为 Linux 发布 Claude Desktop，所以选择一条路径：
Claude Desktop——免费，通过社区构建版：
- 安装社区版 Claude Desktop for Linux 构建版，并用免费的 claude.ai 账户登录
- 打开 Terminal 并运行：
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh- 重启 Claude Desktop，然后问：“你能看到我的 Home Assistant 吗？”
Claude Code——官方 CLI，需要付费 Claude 计划：
- 安装 Claude Code：
curl -fsSL https://claude.ai/install.sh | bash - 配置 ha-mcp，然后运行 claude：
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code- 启动 claude，运行
/mcp确认，然后问：“你能看到我的 Home Assistant 吗？”
完整的 Linux 指南 →
🪟 Windows#
- 前往 claude.ai 并登录（或创建一个免费账户）
- 打开 Windows PowerShell（从开始菜单）并运行：
irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex- 下载 Claude Desktop（或重启：File → Exit）
- 问 Claude：“你能看到我的 Home Assistant 吗？”
- 你现在已连接到演示环境！连接你自己的 Home Assistant →
🧙 面向 15+ 客户端的设置向导#
Claude Code、Gemini CLI、ChatGPT、Open WebUI、VSCode、Cursor 等。
遇到问题？查看 FAQ 与故障排除。
💬 你能用它做什么？#
直接自然地与 Claude 对话即可。以下是一些真实示例：
| 你说 | 会发生什么 |
|---|---|
| “创建一个在日落时打开门廊灯的自动化” | 创建带有正确触发器和动作的自动化 |
| “给我的仪表盘添加一张天气卡片” | 用新卡片更新你的 Lovelace 仪表盘 |
| “运动传感器自动化不工作，调试一下” | 分析执行轨迹、找出问题、建议修复 |
| “让我的早晨例程自动化也打开咖啡机” | 读取现有自动化，添加新动作并更新 |
| “创建一个设置电影模式的脚本：调暗灯光、关闭百叶窗、打开电视” | 创建带有一系列动作的可复用脚本 |
少花时间配置，多花时间享受智能家居。
✨ 功能#
| 类别 | 能力 |
|---|---|
| 🔍 搜索 | 模糊实体搜索、深层配置搜索、系统概览 |
| 🏠 控制 | 任意服务、批量设备控制、实时状态 |
| 🔧 管理 | 自动化、脚本、辅助元素、仪表盘、区域、分区、分组、日历、蓝图 |
| 📊 监控 | 历史、统计、摄像头快照、自动化轨迹、ZHA 设备 |
| 💾 系统 | 备份/恢复、更新、应用、设备注册表 |
| 🔒 安全 | 只读模式开关、按工具启用/禁用、工具安全策略（用户批准）、自动编辑备份 |
模板辅助元素编辑备份通过 HA-MCP 自定义组件捕获持久化选项，使用其 Server 条目或 File & YAML Tools 条目。辅助元素编辑、通用集成选项编辑和删除会捕获稳定的配置条目身份以及实体 ID/名称映射。捕获会拒绝降级的机密擦除。恢复现有辅助元素需要一份新的安全备份，会移除快照中不存在的可选设置，并验证持久化选项。
对于 Template 备份列表和批量删除，请按捕获时作为 entity_id 返回的配置条目 ID 进行筛选。捕获接受实体别名；历史筛选器使用稳定的配置条目 ID。重建会分别报告其替代配置条目 ID 和保存的实体映射。
如果原始条目已被删除，恢复会重新创建辅助元素，并报告其新配置条目 ID。可用时会恢复保存的实体 ID 和自定义名称；创建前会拒绝已占用的实体 ID。没有实体元数据的旧快照无法保留重命名后的实体 ID。如果创建后发生冲突或验证失败，新的辅助元素和源备份会保留，结果会报告新条目供检查。其他实体/设备注册表设置不会恢复。通过同一服务器进行的辅助元素和集成编辑会等待恢复完成；其他 Home Assistant 客户端不在此协调范围内。失败或不确定的恢复会报告其结果和安全拒绝的原因；重试前请检查当前辅助元素。
完整工具列表（87 个工具）#
| 类别 | 工具 |
|---|---|
| 应用（add-ons） | ha_get_app, ha_manage_app |
| 区域与楼层 | ha_list_floors_areas, ha_remove_area_or_floor, ha_set_area_or_floor |
| Assist | ha_manage_pipeline |
| 自动化 | ha_config_get_automation, ha_config_remove_automation, ha_config_set_automation |
| 蓝图 | ha_manage_blueprints |
| 日历 | ha_config_get_calendar_events, ha_config_remove_calendar_event, ha_config_set_calendar_event |
| 摄像头 | ha_get_camera_image |
| 仪表盘 | ha_get_dashboard_screenshot（beta） |
| 仪表盘管理 | ha_config_delete_dashboard_resource, ha_config_delete_dashboard, ha_config_get_dashboard, ha_config_list_dashboard_resources, ha_config_set_dashboard_resource, ha_config_set_dashboard |
| 开发者 | ha_dev_manage_server, ha_dev_manage_settings |
| 设备注册表 | ha_get_device, ha_remove_device, ha_set_device |
| 能源 | ha_manage_energy_prefs |
| 实体注册表 | ha_get_entity_exposure, ha_get_entity, ha_remove_entity, ha_set_entity |
| 文件 | ha_delete_file（beta）, ha_list_files（beta）, ha_read_file（beta）, ha_write_file（beta） |
| 分组 | ha_config_list_groups, ha_config_remove_group, ha_config_set_group |
| HACS | ha_get_hacs_info, ha_manage_hacs |
| 辅助实体 | ha_config_list_helpers, ha_config_set_helper, ha_remove_helpers_integrations |
| 历史与统计 | ha_get_automation_traces, ha_get_history, ha_get_logs |
| 集成 | ha_get_integration, ha_get_system_health, ha_set_integration |
| 标签与类别 | ha_config_get_category, ha_config_get_label, ha_config_remove_category, ha_config_remove_label, ha_config_set_category, ha_config_set_label |
| Matter | ha_manage_radio |
| 场景 | ha_config_get_scene, ha_config_remove_scene, ha_config_set_scene |
| 脚本 | ha_config_get_script, ha_config_remove_script, ha_config_set_script |
| 搜索与发现 | ha_get_overview, ha_get_state, ha_search |
| 服务与设备控制 | ha_bulk_control, ha_call_event, ha_call_service, ha_get_operation_status, ha_list_services |
| 系统 | ha_config_get_yaml（beta）, ha_config_set_yaml（beta）, ha_manage_backup, ha_manage_custom_tool（beta）, ha_manage_security_policy, ha_manage_theme, ha_manage_updates, ha_reload_core, ha_restart |
| 待办列表 | ha_get_todo, ha_remove_todo_item, ha_set_todo_item |
| 实用工具 | ha_eval_template, ha_report_issue |
| 分区 | ha_get_zone, ha_remove_zone, ha_set_zone |
即使 Z-Wave 配置实体被禁用或不存在，也可以通过 ha_manage_radio 的 action="get_config_params" 或 action="get_config_param" 读取 Z-Wave 配置值。读取默认使用 Z-Wave JS 缓存；单个完整根参数可以显式请求设备读取。参见参数读取、时效性和示例。
🆚 ha-mcp 与 Home Assistant 内置 MCP Server#
Home Assistant 自带自己的 MCP Server 集成。它建立在 Assist 管道之上，因此连接的 MCP 客户端可以读取和控制你已暴露给 Assist 的实体，并运行 Assist 能理解的意图——对于已暴露设备的语音式控制很方便。
ha-mcp 是一个独立服务器，专为配置、构建和调试你的智能家居而设计，而不仅仅是控制它。除了设备控制，它还增加了内置集成没有的能力：
| 能力 | 内置 MCP Server | ha-mcp |
|---|---|---|
| 控制已暴露设备、查询状态 | 是 | 是 |
| 实体范围 | 仅暴露给 Assist 的实体 | Home Assistant 中的所有内容 |
| 创建/编辑自动化、脚本、场景 | 否 | 是 |
| 构建与编辑仪表盘 | 否 | 是 |
| 从轨迹调试自动化、读取历史和日志 | 否 | 是 |
| 管理辅助元素、区域、分区、标签、分组 | 否 | 是 |
| 备份、应用、HACS、设备与实体注册表 | 否 | 是 |
经验法则：使用内置集成对你已暴露的设备进行语音式控制；当你想要一个还能构建和维护 Home Assistant 设置的 AI 助手时，使用 ha-mcp。
🔌 自定义组件（ha_mcp_tools）——文件与 YAML 服务#
HA-MCP 集成还提供一组标准 Home Assistant API 无法提供的特权工具：文件系统访问和 YAML 配置编辑。（同一组件在进程内运行完整服务器——这是顶部快速开始部分推荐的安装方式。）它的 File & YAML services 条目（HA-MCP File & YAML Tools）启用下面的工具。
需要该组件的工具：
| 工具 | 描述 |
|---|---|
| ha_config_set_yaml（beta） | 在 configuration.yaml 和包文件中安全添加、替换或删除顶层 YAML 键（自动备份、验证和配置检查） |
| ha_list_files（beta） | 列出允许目录中的文件 |
| ha_read_file（beta） | 从允许路径读取文件（配置 YAML、日志和允许的目录） |
| ha_write_file（beta） | 将文件写入允许的目录 |
| ha_delete_file（beta） | 从允许的目录删除文件 |
模板辅助元素编辑备份和恢复也需要该组件，使用其 Server 条目或 File & YAML Tools 条目。如果组件缺失，这五个工具会返回错误并附带安装说明。
这些工具还需要 beta 功能标志。参见 Beta Features 了解如何启用它们——包括 ENABLE_BETA_FEATURES 总开关，必须先打开它，文件系统/YAML 子标志才会生效。
安装#
从同一个 HA-MCP 集成安装 HA-MCP File & YAML Tools 条目：
需要通过 HACS 或市场使用 Home Assistant 2026.8.0 或更新版本；手动安装请参见兼容性详情。在 Home Assistant 2026.8–2026.10 上：打开 HACS，搜索 HA-MCP，然后点击 Download。在 2026.11 或更新版本上：打开 Marketplace，接受首次运行警告，搜索 HA-MCP，然后点击 Install。主仓库在两者中都位于默认目录。或者将此仓库中的 custom_components/ha_mcp_tools/ 复制到你的 HA config/custom_components/ 目录。
安装后，重启 Home Assistant，然后打开 Settings > Devices & Services > Add Integration，搜索 HA-MCP，并添加 HA-MCP File & YAML Tools 条目。
要通过同一组件在进程内运行完整的 ha-mcp 服务器，请参见顶部快速开始部分和完整的进程内服务器文档 →。
🧠 用 Agent Skills 获得更好的结果#
这个服务器为你的 AI 智能体提供控制 Home Assistant 的工具。为了获得更好的配置，请将它和 Home Assistant Agent Skills 搭配使用——这些领域知识教智能体 Home Assistant 的最佳实践。
MCP 服务器可以创建自动化、辅助元素和仪表盘，但它对如何组织它们没有意见。没有领域知识，智能体往往会过度依赖模板、选错辅助元素类型，或产生难以维护的自动化。技能填补了这个空白：优先使用原生结构而不是 Jinja2 变通方案、正确选择辅助元素、安全的重构工作流，以及正确使用自动化模式。
捆绑技能（内置）#
来自 homeassistant-ai/skills 的技能已捆绑，并作为 MCP 资源通过 skill:// URI 提供。任何支持资源的 MCP 客户端都可以自动发现它们——无需手动安装。对于仅支持工具的客户端（claude.ai 等），最佳实践技能可通过 ha_get_skill_guide 工具访问：不带参数调用它可读取 SKILL.md，或将 file 设为 SKILL.md 链接的路径来读取该参考文件。资源不会自动注入上下文——客户端必须显式请求它们，因此空闲上下文成本只是元数据列表。
ha_get_skill_guide 是强制工具：目录始终暴露它（无法禁用），因此仅支持工具的客户端永远不会看到静默缺失的技能表面。
对于偏好本地技能文件的客户端，仍可手动安装技能——参见技能仓库中的说明。
🔍 面向 AI 智能体的工具发现#
默认情况下，完整工具目录（约 87 个工具）会通过标准 MCP tools/list 响应列给客户端。支持延迟/按需加载工具的客户端（claude.ai、Claude Desktop、Claude Code）可以很好地处理——工具只在需要时被拉入上下文，因此空闲上下文成本接近零。
对于不支持延迟工具的设置——Claude Haiku、Gemini、OpenAI 兼容本地模型和更小的开源权重模型，或无论模型如何都会内联所有工具模式的客户端（例如 GitHub Copilot CLI）——预先列出完整工具目录会增加大量空闲上下文，并可能压垮较小的模型。为解决这个问题，服务器附带一个基于 FastMCP 的 BM25 搜索变换构建的、基于搜索的发现模式。
更小或本地 LLM（Ollama 等）#
如果你的模型看不到工具或你的 Home Assistant，它可能一次性拿到了整个工具目录，难以处理。建议尝试以下方法：
- 启用工具搜索（
ENABLE_TOOL_SEARCH=true，或下方的应用选项）。服务器不会预先列出每个工具，而是把目录放在搜索接口之后，模型只在需要时拉入它需要的工具。 - 将模型的上下文窗口提高到默认值以上。本地运行时附带较小的默认值（Ollama 的
num_ctx是一个例子），无法容纳大型工具集加上对话——请大幅提高默认值。
启用基于搜索的发现#
设置 ENABLE_TOOL_SEARCH=true（或切换 HA 应用中的选项）。完整目录会在工具列表中被替换为四个入口点，加上一小组始终可见的“固定”工具（ha_search、ha_get_overview、ha_report_issue 等）。所有工具在被发现后仍可按名称直接调用：
| 工具 | 用途 |
|---|---|
| ha_search_tools | 跨所有工具（包括固定工具）的 BM25 英文关键词搜索。隐藏工具会以紧凑形式返回：名称、一行描述（docstring 的第一段）、一行参数列表（类型、枚举值、必填）以及执行它的代理。ha_search_tools(tools=[...]) 返回指定工具的完整定义（描述、输入模式和注解），这是调用前的第二跳。固定工具返回仅含名称的存根（pinned: true），指回工具列表，并且不占用结果槽位。 |
| ha_call_read_tool | 按名称执行带有 readOnlyHint 的工具。安全——客户端可以自动批准。 |
| ha_call_write_tool | 执行创建或更新数据的写入工具。 |
| ha_call_delete_tool | 执行删除数据的工具。 |
代理拆分让 MCP 客户端可以按类别应用不同的权限策略（例如自动批准读取、写入时提示、删除时确认），而无需解析工具 docstring。
一个 ha_manage_* 工具组合了多个操作，因此可以从多个代理访问：ha_call_write_tool 和 ha_call_delete_tool 运行整个工具，而 ha_call_read_tool 只运行只读模式批准的读取操作（相同的每次调用判定），因此没有已批准读取操作的 manage 工具无法在那里访问。搜索结果会列出该工具可经由的每个代理。在只读模式下只列出 ha_call_read_tool；另外两个仍会响应在缓存工具列表中持有它们的客户端，并且它们携带的任何写入都会得到只读模式错误，而不是“Unknown tool”。
| 设置 | 默认值 | 描述 |
|---|---|---|
| ENABLE_TOOL_SEARCH | false | 用基于搜索的发现替换完整工具目录（工具延迟到按需搜索之后）。 |
| TOOL_SEARCH_MAX_RESULTS | 5 | 每次 ha_search_tools 调用返回的隐藏工具上限（范围 2–10）；排名进入该数量的固定工具会作为仅名称存根额外添加。 |
| PINNED_TOOLS | 空 | 逗号分隔的、始终保持可见的工具名称。Web 设置 UI 是管理它的主要方式。 |
何时启用：
- Claude Haiku、OpenAI 兼容本地模型、Gemini，或任何没有原生延迟工具支持的模型——大幅节省空闲上下文。对于无论模型如何都会内联所有工具模式的客户端也同样适用（例如 GitHub Copilot CLI，即使运行 Claude Sonnet/Opus）。
- 限制工具总数的 MCP 客户端（有些上限为 100）——呈现最小集合（约 10 个工具）而不是 87 个。
- 对成本敏感的部署——每轮空闲 token 更少。
在支持延迟工具加载的客户端中保持关闭（claude.ai、Claude Desktop、Claude Code）；完整目录在那里没有空闲成本，直接调用会跳过搜索步骤，而且客户端内置的工具搜索是更好的选择——在它之上再运行 ha-mcp 的搜索没有好处。工具是否延迟取决于客户端和模型的组合：同一模型在不同客户端中可能表现不同——GitHub Copilot CLI 在运行 Claude Sonnet/Opus 时会内联完整目录，仍然受益于这里的工具搜索。某些 Codex 模型和 ChatGPT 也包含延迟工具——直接检查你的客户端/模型以确认其功能，以免不必要地启用它。
🔄 更改此设置（或任何设置）后，请刷新客户端的工具列表。 切换 ENABLE_TOOL_SEARCH（或更改固定/禁用工具、只读模式等）会改变服务器暴露的工具，但你的 AI 客户端会继续提供其缓存的工具列表，直到重新获取。重启应用或 Home Assistant 不会刷新客户端——请在客户端中重新连接或刷新 MCP 服务器（例如在 ChatGPT 中打开 Settings，然后打开插件设置，选择连接器并点击 Refresh tools；断开并重新连接 Claude Desktop 自定义连接器；刷新 claude.ai 连接器的工具列表；或者对于 claude_desktop_config.json 中的服务器，退出并重新打开 Claude Desktop），然后开始新对话。如果跳过这一步，新启用的工具根本不会出现在客户端中，而服务器不再暴露的工具仍会显示为可用，但调用时会失败（Unknown tool，或写入工具被只读模式隐藏时的只读模式错误）。ChatGPT 有时即使在同一名称下移除并重新添加连接器后，仍会继续提供过期列表——如果刷新后工具仍然缺失，请删除连接器并以不同名称创建一个新的。FAQ 中有完整步骤。
对于 HA 应用，同一选项记录在 homeassistant-addon/DOCS.md 中，并附有应用内设置 UI，用于细粒度启用/禁用/固定工具。
按 URL 划分的工具目录#
ENABLE_TOOL_SEARCH 默认关闭，它只设置主端点的目录。当多个客户端共享一个服务器时，为每个客户端提供其所需目录的 URL：内置工具搜索的客户端保留完整列表，小上下文客户端获得搜索工具。后缀是固定覆盖，忽略 ENABLE_TOOL_SEARCH：
- 主端点（遵循
ENABLE_TOOL_SEARCH）：https://example.com/private_your_secret - 始终为完整目录：
https://example.com/private_your_secret/catalog/full - 始终为搜索工具：
https://example.com/private_your_secret/catalog/search - 只读、搜索工具：
https://example.com/private_your_secret/readonly/catalog/search
每个 URL 在连接生命周期内保持其目录，因此客户端只能通过给定的 URL 选择目录。更改 URL 后请重新连接客户端，以便刷新工具列表。Home Assistant webhook URL 接受相同的后缀，可单独使用或放在 /readonly 之后：https://your-ha.example/api/webhook/<webhook-id>/catalog/search。这需要提供这些后缀的嵌入式集成或 Webhook Proxy 应用（add-on）发行版，以及匹配的 MCP 服务器；较旧的版本会对带后缀的 URL 返回 404。Stdio 为每个服务器进程运行一个客户端，因此请在该客户端的服务器环境中设置 ENABLE_TOOL_SEARCH。
只读 HTTP 连接#
在服务器的 HTTP MCP 端点后附加 /readonly，将该连接限制为现有的只读模式，而其他客户端保持正常访问：
- 正常：
https://example.com/private_your_secret - 只读：
https://example.com/private_your_secret/readonly
OAuth 和 OIDC 连接使用相同的登录/提供方：例如 https://example.com/mcp/readonly。无需额外的秘密或服务器。只读连接会隐藏写入工具并阻止写入调用，包括通过缓存工具或搜索代理进行的调用。启用全局只读模式设置后，仍会限制两个端点。更改 URL 后请重新连接客户端，以便刷新工具列表。
这是一种供自动化智能体使用的连接模式，而不是凭据上的单独权限：相同的凭据在正常端点仍然有效。Home Assistant webhook URL 也接受该后缀：https://your-ha.example/api/webhook/<webhook-id>/readonly。这需要更新的嵌入式集成或 Webhook Proxy 开发应用（add-on），以及更新的 MCP 服务器。
🧪 开发渠道#
想要提前获得新功能和修复？每次推送到 master 都会发布开发版（.devN）。
开发渠道文档——适用于 pip/uvx、Docker 和 Home Assistant 应用的说明。
🤝 贡献#
开发设置、测试说明和贡献指南，请参见 CONTRIBUTING.md。
完整的测试文档，请参见 tests/README.md。
🔒 隐私#
Ha-mcp 在你的机器上本地运行。你的智能家居数据留在你的网络中。
- 目前无遥测——匿名使用统计是计划中的未来功能（截至 2026 年 6 月）；上线时将遵循你的 Home Assistant 分析/遥测设置（你可以覆盖），并至少提前一个月在发行说明和 Web 设置 UI 中显著公告
- 不收集个人数据——我们从不收集实体名称、配置或设备数据
- 用户控制的错误报告——仅在您明确批准后发送
完整详情请参见我们的隐私政策。
📄 许可证#
本项目采用 MIT 许可证——详情请参见 LICENSE 文件。
🙏 致谢#
- Home Assistant：了不起的智能家居平台！
- FastMCP：优秀的 MCP 服务器框架
- Model Context Protocol：标准化的 AI 应用通信
- Claude Code：AI 驱动的编程助手
- PolicyLayer：参数路径谓词 DSL 形状（
args.domain in [...]，配合 eq/in/regex/contains/exists/...）启发了按工具批准规则模式（#966）
👥 贡献者#
维护者#
- @julienld——项目创建者。
- @sergeykad——核心维护者。
- @kingpanther13——核心维护者。
- @Patch76——核心维护者。
贡献者#
- @bigeric08——为协议版本 2025-11-25 支持添加显式 mcp 依赖。
- @airlabno——支持 schedule 时间块中的 data 字段。
- @ryphez——Codex Desktop UI MCP 快速设置指南。
- @Danm72——实体注册表工具（ha_set_entity、ha_get_entity），用于管理实体属性。
- @Raygooo——SOCKS 代理支持。
- @cj-elevate——集成与实体管理工具（启用/禁用/删除）；person/zone/tag 配置存储路由。
- @maxperron——Beta 测试。
- @kingbear2——Windows UV 设置指南。
- @konradwalsh——通过 GitHub Sponsors 提供财务支持。谢谢！☕
- @knowald——在 ha_get_system_overview 中通过设备注册表解析区域，用于通过父设备分配的实体。通过 GitHub Sponsors 提供财务支持。谢谢！☕
- @zorrobyte——OAuth 模式下的按客户端 WebSocket 凭据，修复 WebSocket 工具故障。
- @deanbenson——修复大型 Home Assistant 实例（包含大量自动化）上的 ha_deep_search 超时。
- @saphid——配置条目选项流工具（初始设计，#590）。
- @adraguidev——修复基于菜单的配置条目流中的分组辅助元素（#647）。
- @transportrefer——集成选项检查（ha_get_integration 模式支持，#689）。
- @teh-hippo——修复蓝图导入缺少保存步骤。
- @smenzer——文档修复。
- @The-Greg-O——用于配置条目删除的 REST API。
- @restriction——负责任披露：python_transform 沙箱缺少调用目标验证。
- @lcrostarosa——诊断与健康监控工具概念（#675），启发了系统/错误日志、修复和 ZHA 无线电指标集成。
- @roysha1——安装向导中的 Copilot CLI 支持；在文档站点上用真实品牌图标替换了占位 logo SVG。
- @teancom——修复 add-on 统计端点（
/addons/{slug}/stats）。 - @TomasDJo——自动化、脚本和场景的类别支持。
- @bzelch——自动化和脚本的 python_transform 支持。
- @gcormier——Windows 安装器改进：移除未使用变量并修复安装后终端关闭问题。
- @ekobres——应用配置中 HAMCP_ENABLE_FILESYSTEM_TOOLS 和（后来移除的）HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION 的功能标志，在源码和文档中添加 beta 标记。
- @w3z315——通过 GitHub Sponsors 提供财务支持。谢谢！☕
- @griffinmartin——在设置向导中添加 OpenCode（由 Anomaly 开发）作为可选 AI 客户端，支持 stdio 和可流式 HTTP。
- @hhopke——修复应用（add-on）API 调用，使其通过 HA Core ingress 代理路由，而不是直接连接容器，修复应用安装上的 ha_manage_addon（现为 ha_manage_app）代理模式。
- @tomwilkie——JMESPath 中间件探索（#1147），其评审期间的 token 测量数据影响了 #1199 和 #1225 的设计。
- @SealKan——六个读取密集型工具上的 fields=/attribute_keys= 投影（#1225）、ha_call_event 工具（#1239）、仪表盘列表辅助元素重构（#1207）、最佳实践检查器中的 for: 字段时长数学检测器（#1264）、跨重启的持久 DCR OAuth 客户端注册（#1265），以及 issue 分类提示词的 token 预算（#1522）。
- @KarelTestSpecial——缓存 YAML 实例，防止批量编辑期间 CPU 峰值（#1371）。
- @corgan2222——自定义集成的 HA 品牌资产（#1317）。
- @drseanwing——在长时间运行工具中通过 FastMCP Context 发出进度（#1124）；工具发现/分类搜索文档（#1123）。
- @fnordpig——配置子条目支持（#1393）和 Assist 管道管理工具（#1392）。
- @paul43210——ha_manage_app 中的 array_patch 模式，用于原子 GET-modify-POST（#1063）。
- @L1AD——提交 #966 提出工具安全策略；指出 PolicyLayer 的 MCP 安全工作作为启发了谓词 DSL 形状的先前技术。
- @nightcityblade——在 HA 2026.6 使原高级选项默认可用后，更新了过时的 Home Assistant 高级模式引用（#1533）。
- @emmelutzer——通过 GitHub Sponsors 提供财务支持。谢谢！☕
- @pkkr——ha_knx_get_project 工具，从上传的 ETS 项目文件公开 KNX 组地址。
- @cbowns——修复 setup.astro Codex CLI 文档中不一致的连字符。
- @Shaan-alpha——扩展 ha_restart 已知良好错误模式，以覆盖反向代理的 502/503 响应。
- @rebelancap——修复 add_timezone_metadata 中的 UTC 到本地时区转换。
- @saevras——修复蓝图导入 E2E 测试，使用本地 URL 而不是主机到容器网络。
- @jasonjhofmann——在 ha_config_set_calendar_event 中通过 rrule 支持重复日历事件。
- @vpciii——在 dict/list 工具参数上强制转换 JSON 编码字符串。
- @pburtchaell——通过 GitHub Sponsors 提供财务支持。谢谢！☕
- @norpol——构建 OpenAI Tunnel for HA-MCP 配套集成，将 ChatGPT 连接到防火墙后的 Home Assistant MCP 服务器（#1811）。
💬 社区#
- GitHub Discussions——提问、分享想法
- Issue Tracker——报告 bug、请求功能或建议改进工具行为。Bug 报告需要 ha_report_issue 工具生成的报告，或说明为何没有；两者都没有的报告会在 24 小时后关闭。