mcpField
H
ha-mcp

ha-mcp

本地服务
github.com/homeassistant-ai其他5.3k今天更新
代码仓库

关于 ha-mcp

ha-mcp 是用于通过 AI 助手控制和管理 Home Assistant 的 MCP 服务。它让客户端控制设备、查询状态、执行服务和管理自动化，并支持进程内及外部 HTTP 部署。

主要功能

  1. 01控制智能家居设备
  2. 02查询实体状态
  3. 03执行 Home Assistant 服务
  4. 04管理自动化
  5. 05支持进程内和 HTTP 部署

适用场景

  1. 01用自然语言控制设备
  2. 02查看 Home Assistant 状态
  3. 03执行服务并管理自动化

MCP 相关

它向 MCP 客户端开放 Home Assistant 设备控制、状态查询、服务执行和自动化管理。客户端通过配置的 URL 连接，可选部署方式包括进程内组件和外部 HTTP 服务。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "homeassistant-ai-ha": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}
启动命令uvx ha-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypiha-mcp9.0.0
ocighcr.io/homeassistant-ai/ha-mcp:9.0.0

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

破坏性变更（v7.3.0）： ha_config_set_yaml 已移至测试版。

Home Assistant MCP 服务徽标

非官方且出色的 Home Assistant MCP 服务

87 个工具 发布版本 端到端测试 许可证
活跃度 基于 FastMCP 构建 Python 版本 GitHub 赞助者 网站

一个功能全面的 Model Context Protocol（MCP）服务，可让 AI 助手与 Home Assistant 交互。
使用自然语言控制智能家居设备、查询状态、执行服务并管理自动化。

Claude Desktop 演示

🚀 快速开始

推荐的 ha-mcp 运行方式是 HA-MCP 自定义集成。它通过 HACS 安装到 Home Assistant 中，在进程内运行完整服务，并适用于所有 Home Assistant 安装类型——Home Assistant OS、Supervised、Container 和 Core——功能完全一致。无论哪种情况，这都是最简单的设置方式：设置过程会要求提供管理员访问令牌，并选择客户端的连接方式。

通过 HACS 将其添加到 Home Assistant（推荐安装方式）：

将 HA-MCP 添加到 HACS

快速入门：

以下设置适用于 2026 年 10 月 28 日及之后发布的 9.0.0 版本；更早版本显示的设置表单较短，不包含管理员账户步骤。

  1. 通过 HACS 安装 HA-MCP Custom Component——点击上方徽章，或在 HACS 中打开 Integrations → ⋮ → Custom repositories，添加 https://github.com/homeassistant-ai/ha-mcp（类别：Integration），然后点击 Download。 已从之前的 homeassistant-ai/ha-mcp-integration 仓库安装？它仍会收到相同的版本更新；无需更改。
  2. 重启 Home Assistant。
  3. 确定服务器要使用哪个管理员帐户。你可以在自己的帐户中创建长期访问令牌（个人资料 → Security → Long-lived access tokens → Create token；如果令牌泄露，任何人都可以从任何位置使用它，服务器所做的更改也会显示在你的名下）；或者，为 HA-MCP 创建一个专用帐户（更安全）：打开 Settings → People → Add person，启用 Allow login、Local access only 和 Administrator。选择第二种方式时，绝不要使用自己的登录帐户。
  4. 前往 Settings → Devices & Services → Add Integration，搜索 HA-MCP Custom Component 并选择 HA-MCP Server。粘贴你的令牌，或输入为 HA-MCP 创建的帐户的用户名和密码（HA-MCP 会创建令牌）；选择客户端的连接方式——Remote access through Home Assistant（建议从 Secret URL 开始，这是最简单的方式；Home Assistant sign-in 会增加登录步骤）和/或 Network access: Local network——然后点击 Submit。这两种方式默认都处于禁用状态，因此其他设备上的客户端需要启用其中一种。
  5. 从条目的 Configure 屏幕复制连接 URL（Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure）。通知会确认服务器已启动，并指引你前往该页面。
  6. 将该 URL 粘贴到你的 AI 客户端中——完成。

连接 URL。 Configure 屏幕会提供一个供远程客户端使用的 Home Assistant webhook URL——通过 Nabu Casa 或已指向 Home Assistant 的反向代理访问时，使用 https://<your-ha-domain>/api/webhook/<webhook-id>（本地访问时使用 http://<ha-host>:8123/api/webhook/<webhook-id>）。同一网络中的客户端也可以直接访问服务器：http://<ha-ip>:9584/private_<random>。

  • **取代其他安装方式：**进程内服务器是完整、独立的 ha-mcp 安装方式——它取代 app（附加组件）、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 entry（HA-MCP File & YAML Tools）——只有在启用 ha-mcp 的文件和 YAML 编辑工具（可选功能标志，默认关闭）时才需要；否则请跳过，之后随时可以添加。它适用于任何服务器类型（进程内、app、Docker 或 stdio）。

完整的进程内服务器文档 → · 客户端专属配置的设置向导 →

🏠 Home Assistant 应用（附加组件）

更希望将 ha-mcp 作为 Home Assistant **应用（附加组件）**运行？在 Home Assistant OS 和 Supervised 安装中，这是一个很不错的选择——无需管理访问令牌，并且可与 Claude Desktop、Claude.ai、ChatGPT 以及本地网络中的任何其他 MCP 客户端或配置为远程访问的客户端配合使用。

  1. 将仓库添加到 Home Assistant 实例：

    添加仓库

    如果打开的是应用商店，且没有出现添加仓库对话框（这是一个已知的 Home Assistant 问题），请手动添加：设置 → 应用 → 安装应用 → ⋮ → 仓库，然后粘贴 https://github.com/homeassistant-ai/ha-mcp。

  2. 在 设置 → 应用 → 安装应用 中安装 “Home Assistant MCP Server”，然后点击 启动。（Home Assistant 2026.2 将“附加组件”更名为“应用”；旧版本中此处为附加组件商店。）

  3. 打开 日志标签页，查找专属的 MCP URL。

  4. 将 AI 客户端连接到该 URL——无需设置令牌或凭据。

完整的应用文档 →

⚠️ 每个客户端只能配置一种安装方式。 自定义集成、应用、Docker/PyPI 和本地 stdio 是运行同一服务的独立方式——选择一种，并让 AI 客户端连接到该方式对应的唯一 URL。在同一个客户端中为同一服务保留两个条目（例如，一个本地 uvx ha-mcp@latest 条目，设置了 HOMEASSISTANT_URL / HOMEASSISTANT_TOKEN，同时还配置了应用或集成 URL），是导致连接挂起的已知原因。

其他安装方式

这些方式会在 Home Assistant 外部运行服务，适用于容器/核心安装（无法运行应用）或独立主机。设置向导会为每个客户端生成准确的专属配置。

  • 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。下方演示服务部分中的一键安装程序使用这种方式；设置向导介绍了如何将其连接到你自己的 Home Assistant。

  • OIDC 身份验证： 通过外部身份提供商（Authentik、Keycloak、Auth0 等）限制远程访问，而不是使用专属 URL——所有通过身份验证的用户共用服务的 Home Assistant 凭据。请参阅 OIDC 模式。

    ⚠️ stdio 存在已知的传输问题。 stdio 传输存在连接问题，而可流式传输的 HTTP 没有此问题（#1713）。stdio 仅建议用于演示、测试和尝试；实际部署请使用自定义组件或上述 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 流量——无需单独的隧道或端口转发。

  1. 安装 MCP Server 应用（见上文）以及同一商店中的 Webhook Proxy 应用
  2. 启动 webhook proxy，并在出现提示时重启 Home Assistant
  3. 从应用日志中复制 webhook URL： 
    MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx
  4. 使用该 URL 配置 AI 客户端

如需了解其他远程访问方式（Cloudflare Tunnel、自定义反向代理），请参阅设置向导。

防火墙后的 ChatGPT / Codex（OpenAI Tunnel）。 ChatGPT 连接器通常需要一个可从公网访问的 URL。如果你无法（或不想）公开此类 URL，社区提供的 OpenAI Tunnel for HA-MCP 集成由 @norpol 开发，可在 Home Assistant 内运行 OpenAI 的 tunnel-client，并通过仅出站连接将本地 MCP 服务 URL 连接到由 OpenAI 托管的隧道——无需端口转发、反向代理或公开 URL。将其指向你的 ha-mcp URL，然后将 ChatGPT 连接器连接到同一个隧道 ID。请参阅 FAQ 条目和 #1811。

Webhook proxy 文档 →

### 🧪 演示服务（Windows / macOS / Linux）

想在连接自己的 Home Assistant 之前先试用 ha-mcp？*无需付费订阅。*这些一键脚本会设置与托管演示环境的本地 stdio 连接，让你在几分钟内看到它运行起来。每个脚本中的连接自己的 Home Assistant链接会介绍如何将其指向你的实例。

🍎 macOS
  1. 前往 claude.ai 并登录（或创建免费账户）
  2. 打开终端并运行： 
    curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh
  3. 下载 Claude Desktop（或重启：Claude 菜单 → 退出）
  4. 询问 Claude：“能看到我的 Home Assistant 吗？”

现在你已连接到演示环境！连接自己的 Home Assistant →

🐧 Linux

Anthropic 未提供适用于 Linux 的 Claude Desktop，因此请选择一种方式：

Claude Desktop — 通过社区构建版本免费使用：

  1. 安装社区提供的 Claude Desktop for Linux 构建版本，并使用免费的 claude.ai 账户登录
  2. 打开终端并运行： 
    curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
  3. 重启 Claude Desktop，然后询问：“能看到我的 Home Assistant 吗？”

Claude Code — 官方 CLI，需要付费 Claude 计划：

  1. 安装 Claude Code：curl -fsSL https://claude.ai/install.sh | bash
  2. 配置 ha-mcp，然后运行 claude： 
    curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code
  3. 启动 claude，运行 /mcp 进行确认，然后询问：“能看到我的 Home Assistant 吗？”

Linux 完整指南 →

🪟 Windows
  1. 前往 claude.ai 并登录（或创建免费账户）
  2. 打开Windows PowerShell（从“开始”菜单打开）并运行： 
    irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex
  3. 下载 Claude Desktop（或重启：文件 → 退出）
  4. 询问 Claude：“能看到我的 Home Assistant 吗？”

现在你已连接到演示环境！连接自己的 Home Assistant →

🧙 适用于 15+ 个客户端的设置向导

Claude Code、Gemini CLI、ChatGPT、Open WebUI、VSCode、Cursor 等。

打开设置向导

遇到问题？请查看**常见问题与故障排除**

💬 你可以用它做什么？

只需自然地与 Claude 对话。以下是一些实际示例：

你说会发生什么
“创建一个在日落时打开门廊灯的自动化”创建包含适当触发器和操作的自动化
“在我的仪表盘上添加一个天气卡片”使用新卡片更新你的 Lovelace 仪表盘
“动作传感器自动化不起作用，帮我调试一下”分析执行跟踪记录、找出问题并建议修复方法
“让我的晨间例程自动化也打开咖啡机”读取现有自动化，添加新操作并更新它
“创建一个设置观影模式的脚本：调暗灯光、关闭百叶窗、打开电视”创建一个包含操作序列的可重复使用脚本

少花些时间配置，多享受智能家居生活。

✨ 功能

类别功能
🔍 搜索模糊实体搜索、深度配置搜索、系统概览
🏠 控制任意服务、批量设备控制、实时状态
🔧 管理自动化、脚本、辅助项、仪表板、区域、地带、组、日历、蓝图
📊 监控历史记录、统计数据、摄像头快照、自动化跟踪记录、ZHA 设备
💾 系统备份/恢复、更新、应用、设备注册表
🔒 安全只读模式开关、按工具启用/禁用、工具安全策略（用户审批）、自动编辑备份

模板辅助项编辑备份通过 HA-MCP 自定义组件捕获已持久化的选项，可使用其 Server 条目或 File & YAML Tools 条目。辅助项编辑、通用集成选项编辑和删除操作会捕获稳定的配置条目标识以及实体 ID/名称映射。若密钥清理效果不佳，则拒绝捕获。恢复现有辅助项需要先创建新的安全备份，会移除快照中不存在的可选设置，并验证已持久化的选项。

对于模板备份的列表和批量删除，请使用捕获操作以 entity_id 返回的配置条目 ID 进行筛选。捕获操作接受实体别名；历史记录筛选器使用稳定的配置条目 ID。重新创建操作会分别报告替代配置条目 ID 和已保存的实体映射。

如果原始条目已被删除，恢复操作会重新创建该辅助项并报告其新的配置条目 ID。若可用，则会恢复已保存的实体 ID 和自定义名称；如果实体 ID 已被占用，则会在创建前拒绝操作。缺少实体元数据的旧快照无法保留已重命名的实体 ID。如果创建后发生冲突或验证失败，新辅助项和源备份会予以保留，结果中会报告新的条目，供检查使用。其他实体/设备注册表设置不会恢复。通过同一服务进行的辅助项和集成编辑会等待恢复完成；其他 Home Assistant 客户端不受此协调机制约束。恢复失败或结果不确定时，会报告操作结果和安全拒绝原因；重试前请检查当前辅助项。

完整工具列表（87 个工具） | 类别 | 工具 | |----------|-------| | **应用（附加组件）** | `ha_get_app`、`ha_manage_app` | | **区域与楼层** | `ha_list_floors_areas`、`ha_remove_area_or_floor`、`ha_set_area_or_floor` | | **语音助手** | `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` *（测试版）* | | **仪表板** | `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` *（测试版）*、`ha_list_files` *（测试版）*、`ha_read_file` *（测试版）*、`ha_write_file` *（测试版）* | | **组** | `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` *（测试版）*、`ha_config_set_yaml` *（测试版）*、`ha_manage_backup`、`ha_manage_custom_tool` *（测试版）*、`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 Serverha-mcp
控制已开放的设备、查询状态是是
实体范围仅向 Assist 开放的实体Home Assistant 中的所有实体
创建 / 编辑自动化、脚本、场景否是
构建和编辑仪表盘否是
根据追踪调试自动化、读取历史记录和日志否是
管理辅助项、区域、区域围栏、标签、组否是
备份、应用、HACS、设备和实体注册表否是

经验法则： 如果要通过语音方式控制已开放的设备，请使用内置集成；如果希望 AI 助手也能构建和维护 Home Assistant 配置，请使用 ha-mcp。

🔌 自定义组件（ha_mcp_tools）— 文件和 YAML 服务

HA-MCP 自定义组件还支持一组标准 Home Assistant API 无法提供的特权工具：文件系统访问和 YAML 配置编辑。（同一组件也可在进程内运行完整服务——顶部的 开始使用 部分推荐采用这种安装方式。）它的文件和 YAML 服务条目（HA-MCP 文件和 YAML 工具）可启用以下工具。

需要此组件的工具：

工具说明
ha_config_set_yaml (beta)安全地添加、替换或移除 configuration.yaml 和 package 文件中的顶层 YAML 键（自动备份、验证和配置检查）
ha_list_files (beta)列出允许访问的目录中的文件
ha_read_file (beta)读取允许路径中的文件（配置 YAML、日志和允许访问的目录）
ha_write_file (beta)向允许访问的目录写入文件
ha_delete_file (beta)删除允许访问的目录中的文件

模板辅助项编辑的备份和还原也需要此组件，可使用其 Server 条目或文件和 YAML 工具条目。如果缺少该组件，这五种工具会返回错误并附上安装说明。

这些工具还需要启用 beta 功能标志。请参阅 Beta 功能，了解如何启用，包括必须先开启的 ENABLE_BETA_FEATURES 主标志；只有开启此标志后，文件系统 / YAML 子标志才会生效。

安装

从同一个 HA-MCP 自定义组件安装 HA-MCP 文件和 YAML 工具条目：

打开你的 Home Assistant 实例，并在 Home Assistant Community Store 中打开一个仓库。

手动添加：打开 HACS > 集成 > 三点菜单 > 自定义仓库 > 添加 https://github.com/homeassistant-ai/ha-mcp（类别：集成）> 下载。或者，将此仓库中的 custom_components/ha_mcp_tools/ 复制到 HA 的 config/custom_components/ 目录。

安装后，重启 Home Assistant，然后打开 设置 > 设备与服务 > 添加集成，搜索 HA-MCP 自定义组件，并添加 HA-MCP 文件和 YAML 工具条目。

如需通过此组件在进程内运行完整的 ha-mcp 服务，请参阅顶部的 开始使用 部分，以及完整的进程内服务文档 →。

🧠 借助 Agent Skills 获得更好的结果

此服务为你的 AI Agent 提供控制 Home Assistant 的工具。为了获得更好的配置，可将其与 Home Assistant Agent Skills 搭配使用——这些领域知识可帮助 Agent 掌握 Home Assistant 的最佳实践。

MCP 服务可以创建自动化、辅助工具和仪表盘，但它不会对如何组织这些内容提出建议。缺少领域知识时，Agent 往往会过度依赖模板、选错辅助工具类型，或生成难以维护的自动化。Skills 可弥补这一不足：优先使用原生结构，而非通过 Jinja2 变通；正确选择辅助工具；采用安全的重构工作流；并恰当使用自动化模式。

内置 Skills

homeassistant-ai/skills 中的 Skills 会随服务打包，并通过 skill:// URI 作为 MCP 资源提供。任何支持资源的 MCP 客户端都可以自动发现它们，无需手动安装。对于仅支持工具的客户端（claude.ai 等），可通过 ha_get_skill_guide 工具获取最佳实践 Skill：不带参数调用即可阅读 SKILL.md；将 file 设为 SKILL.md 链接到的路径，即可阅读相应参考文件。资源不会自动注入上下文——客户端必须主动请求，因此空闲时的上下文开销仅为元数据列表。

ha_get_skill_guide 是必需工具：目录始终会公开此工具（无法禁用），因此仅支持工具的客户端不会遇到 Skill 入口悄然缺失的情况。

对于偏好使用本地 Skill 文件的客户端，仍可手动安装 Skills——请参阅 Skills 仓库中的说明。

🔍 为 AI Agent 发现工具

默认情况下，完整工具目录（约 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 在所有工具中按英文关键词搜索，包括固定工具。隐藏工具会以精简形式返回：名称、一行描述（文档字符串的第一段）、一行 params 列表（类型、枚举值、是否必需），以及执行该工具的代理。ha_search_tools(tools=[...]) 会返回指定工具的完整定义（描述、输入架构和注解），这是调用前的第二步。固定工具会返回仅含名称的存根（pinned: true），指向工具列表，且不会占用结果名额。
ha_call_read_tool按名称执行带有 readOnlyHint 的工具。安全——客户端可自动批准。
ha_call_write_tool执行会创建或更新数据的写入工具。
ha_call_delete_tool执行会移除或删除数据的工具。

代理拆分让 MCP 客户端能够按类别应用不同的权限策略（例如，自动批准读取、对写入进行提示、确认删除），而无需解析工具文档字符串。

一个 ha_manage_* 工具会组合多个操作，因此可通过多个代理调用：ha_call_write_tool 和 ha_call_delete_tool 会运行整个工具，而 ha_call_read_tool 只会运行 Read Only Mode 批准的读取操作（使用相同的逐次调用判定），因此没有任何已批准读取操作的管理工具无法通过该代理调用。搜索结果会列出可调用该工具的每个代理。在 Read Only Mode 下，只会列出 ha_call_read_tool；另外两个仍会响应持有缓存工具列表的客户端，而它们执行的任何写入操作都会返回 Read Only Mode 错误，而不是 Unknown tool。

设置默认值描述
ENABLE_TOOL_SEARCHfalse将完整工具目录替换为基于搜索的发现方式（工具通过按需搜索延迟加载）。
TOOL_SEARCH_MAX_RESULTS5每次 ha_search_tools 调用最多返回的隐藏工具数（范围为 2–10）；在该数量范围内排名靠前的固定工具会以仅含名称的存根形式额外添加。
PINNED_TOOLS空以逗号分隔的工具名称列表，这些工具将始终可见。网页设置界面是管理此项的主要方式。
何时启用
  • 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 中重新添加/刷新连接器，或关闭并重新打开 Claude Desktop）。如果跳过此步骤，新启用的工具根本不会出现在客户端中，而服务端不再公开的工具仍会显示为可用，但调用时会失败（出现 Unknown tool，或对于该模式隐藏的写入工具，出现只读模式错误）。有时，即使在 ChatGPT 中移除连接器并以相同名称重新添加，它仍会继续提供过时的列表——如果重新添加后工具仍然缺失，请删除连接器并使用不同的名称创建一个新的。

对于 HA 应用，同一选项记录在 homeassistant-addon/DOCS.md 中，其中还介绍了应用内用于精细启用/禁用/固定工具的设置界面。

只读 HTTP 连接

在服务端的 HTTP MCP 端点后追加 /readonly，即可将该连接限制为现有的只读模式，同时其他客户端仍可正常访问：

Normal:     https://example.com/private_your_secret
Read-only:  https://example.com/private_your_secret/readonly

OAuth 和 OIDC 连接使用相同的登录方式/提供方，例如： https://example.com/mcp/readonly。无需额外的密钥或服务。 只读连接会隐藏写入工具并阻止写入调用，包括通过缓存工具或搜索代理发起的调用。启用全局只读模式设置后，两个端点都会受到限制。更改 URL 后，请重新连接客户端以刷新其工具列表。

这是供自动化 Agent 使用的连接模式，不是凭证上的单独权限：同一凭证仍可用于常规端点。Home Assistant webhook URL 也接受此后缀： https://your-ha.example/api/webhook/<webhook-id>/readonly。这需要更新后的嵌入式集成或 Webhook Proxy dev app（加载项），以及更新后的 MCP 服务。

🧪 开发频道

想抢先体验新功能和修复？每次推送到 master 时都会发布开发版（.devN）。

开发频道文档——涵盖 pip/uvx、Docker 和 Home Assistant 应用的说明。

🤝 参与贡献

有关开发环境设置、测试说明和贡献指南，请参阅 CONTRIBUTING.md。

有关完整的测试文档，请参阅 tests/README.md。

🔒 隐私

Ha-mcp 在你的计算机上本地运行。智能家居数据会保留在你的网络中。

  • 目前不收集遥测数据 — 匿名使用情况统计是计划中的未来功能（截至 2026 年 6 月）；推出后将遵循你的 Home Assistant 分析/遥测设置（你可以覆盖此设置），并至少提前一个月在发行说明和 Web 设置界面中显著公告
  • 不收集个人数据 — 我们绝不会收集实体名称、配置或设备数据
  • 由用户控制的错误报告 — 仅在你明确批准后发送

完整详情请参阅我们的隐私政策。

📄 许可证

本项目采用 MIT 许可证授权 — 详情请参阅 LICENSE 文件。

🙏 致谢

  • Home Assistant：出色的智能家居平台（！）
  • FastMCP：优秀的 MCP 服务框架
  • Model Context Protocol：标准化 AI 应用通信
  • Claude Code：由 AI 驱动的编码助手
  • PolicyLayer：参数路径谓词 DSL 形式（args.domain in [...]，支持 eq/in/regex/contains/exists/...）为按工具设置的审批规则模式提供了灵感（#966）。

👥 贡献者

维护者
贡献者
  • @bigeric08 — 添加显式 mcp 依赖，以支持协议版本 2025-11-25。
  • @airlabno — 支持在日程时间块中使用 data 字段。
  • @ryphez — Codex Desktop UI MCP 快速设置指南。
  • @Danm72 — 实体注册表工具（ha_set_entity、ha_get_entity），用于管理实体属性。
  • @Raygooo — 支持 SOCKS 代理。
  • @cj-elevate — 集成与实体管理工具（启用／禁用／删除）；人员／区域／标签配置存储路由。
  • @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 — 修复附加组件统计信息端点（/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 和 streamable HTTP。
  • @hhopke — 修复应用（附加组件）API 调用，使其通过 HA Core ingress 代理路由，而非直接连接容器；由此修复应用安装中 ha_manage_addon（现为 ha_manage_app）的代理模式。
  • @tomwilkie — JMESPath 中间件探索（#1147）；其审查时的令牌测量数据为 #1199 和 #1225 的设计提供了参考。
  • @SealKan — 为六个读取密集型工具添加 fields=／attribute_keys= 投影（#1225）；添加 ha_call_event 工具（#1239）；重构仪表盘列表辅助工具（#1207）；在最佳实践检查器中添加 for: 字段时长计算检测器（#1264）；支持 DCR OAuth 客户端注册信息在重启后持久化（#1265）；为问题分类提示词设置令牌预算（#1522）。
  • @KarelTestSpecial — 缓存 YAML 实例，以防止批量编辑时 CPU 使用率激增（#1371）。
  • @corgan2222 — 为自定义集成添加 HA 品牌素材（#1317）。
  • @drseanwing — 通过 FastMCP Context 在长时间运行的工具中发送进度信息（#1124）；编写工具发现／分类搜索文档（#1123）。
  • @fnordpig — 支持配置子条目（#1393），并添加 Assist 流程管理工具（#1392）。
  • @paul43210 — 在 ha_manage_app 中添加 array_patch 模式，以实现原子化 GET-修改-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 — 将字典／列表工具参数中的 JSON 编码字符串转换为对应类型。
  • @pburtchaell — 通过 GitHub Sponsors 提供资金支持。感谢！☕
  • @norpol — 开发了 OpenAI Tunnel for HA-MCP 配套集成，让 ChatGPT 能够连接受防火墙保护的 Home Assistant MCP 服务（#1811）。

💬 社区

  • GitHub 讨论区 — 提问、分享想法
  • 问题跟踪器 — 报告错误、请求功能，或建议改进工具行为。错误报告需要附上 ha_report_issue 工具生成的报告，或说明为何没有报告；缺少两者时，问题会在 24 小时后关闭。

Star 历史

homeassistant-ai/ha-mcp 的 Star 历史图表

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。