ha-mcp-integration

# HA-MCP 自定义组件 HACS 分发存储库，用于 ha-mcp 自定义集成。真相来源是主存储库 - [homeassistant-ai/ha-mcp](https://github.com/homeassistant-ai/ha-mcp) - 它会自动同步此存储库。 - **稳定版**: 安装最新版本（HACS 中的默认设置）。 - **开发版**: 在 HACS 中选择 `main` 分支以跟踪最新版本。 请在 [主存储库](https://github.com/homeassistant-ai/ha-mcp/issues) - 上打开问题和拉取请求，此镜像不携带任何手动更改。 --- > **重大更改（v7.3.0）：** `ha_config_set_yaml` 已移动到 [beta](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/beta.md)。 <div align="center"> <img src="https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/docs/img/ha-mcp-logo.png" alt="Home Assistant MCP Server Logo" width="300"/> # 非官方的 Home Assistant MCP 服务器 <!-- mcp-name: io.github.homeassistant-ai/ha-mcp --> <p align="center"> <img src="https://img.shields.io/badge/tools-85-blue" alt="95+ 工具"> <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="版本"></a> <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E 测试"></a> <a href="https://github.com/homeassistant-ai/ha-mcp/blob/master/LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="许可证"></a> <br> <a href="https://github.com/homeassistant-ai/ha-mcp/commits/master"><img src="https://img.shields.io/github/commit-activity/m/homeassistant-ai/ha-mcp.svg" alt="活动"></a> <a href="https://github.com/jlowin/fastmcp"><img src="https://img.shields.io/badge/Built%20with-FastMCP-purple" alt="Built with FastMCP"></a> <img src="https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fhomeassistant-ai%2Fha-mcp%2Fmaster%2Fpyproject.toml" alt="Python 版本"> <a href="https://github.com/sponsors/julienld"><img src="https://img.shields.io/badge/GitHub_Sponsors-☕-blueviolet" alt="GitHub 赞助者"></a> <a href="https://homeassistant-ai.github.io/ha-mcp/"><img src="https://img.shields.io/badge/Website-docs-teal" alt="网站"></a> </p> <p align="center"> <em>一个全面的模型上下文协议（MCP）服务器，使 AI 助手能够与 Home Assistant 交互。<br> 使用自然语言，控制智能家居设备，查询状态，执行服务和管理自动化。</em> </p> </div> ---  --- ## 🚀 开始使用 推荐使用 **HA-MCP 自定义组件** 运行 ha-mcp。它通过 HACS 安装到 Home Assistant 中，在进程中运行完整的服务器，并支持 **所有** Home Assistant 安装类型 — Home Assistant OS、Supervised、Container 和 Core — 功能齐全。 这是每种情况下最简单的设置，无需管理访问令牌。 **通过 HACS 添加到 Home Assistant（首选安装）：** [](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp-integration&category=integration) **快速入门：** 1. 从 HACS **安装 HA-MCP 自定义组件** - 点击上面的徽章，或在 HACS 中打开 **集成 → ⋮ → 自定义存储库**，添加 `https://github.com/homeassistant-ai/ha-mcp-integration`（类别：**集成**），然后 **下载**。 2. **重启 Home Assistant.** 3. 进入 **设置 → 设备和服务 → 添加集成**，搜索 **HA-MCP 自定义组件**，选择 **HA-MCP 服务器**，然后点击 **提交**。创建条目将启动服务器。 4. 从条目的 **配置** 页面复制连接 URL（也打印在 Home Assistant 日志中）。通知确认服务器已启动并指向那里。 5. 将该 URL 粘贴到您的 AI 客户端中 - 完成。 **连接 URL.** 配置屏幕为您提供了一个用于远程客户端的 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>` 访问。 - **仅限本地？** 在条目选项中关闭 **通过 webhook 进行远程访问** - 不会注册 webhook， 而直接端口和侧边栏面板将继续工作。 - **设置面板：** 当服务器运行时，管理员专用的 **HA-MCP** 面板将出现在 Home Assistant 侧边栏中，用于管理工具、功能标志、备份和主题。 - **可选身份验证：** 将 **Webhook 身份验证** 设置为 `ha_auth`，以要求 Home Assistant 帐户登录，而不是使用机密 URL 作为凭证。 - **手动安装（无 HACS）：** 将此存储库中的 `custom_components/ha_mcp_tools/` 复制到您的 Home Assistant `config/custom_components/` 目录中，然后重启并添加集成，如上所述。 该组件的第二种条目类型，**HA MCP 工具**，仅在您启用 ha-mcp 的可选文件和 YAML 编辑工具（默认情况下为关闭状态）时需要 - 否则跳过它；您可以稍后随时添加它。 [完整进程内服务器文档 →](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/in-process-server.md) · [客户端特定配置的设置向导 →](https://homeassistant-ai.github.io/ha-mcp/setup/) ### 🏠 Home Assistant 应用（附加组件） 是否更喜欢将 ha-mcp 作为 Home Assistant **应用 / 附加组件** 运行？在 **Home Assistant OS** 和 **Supervised** 安装中，它是第二种选择 - 无需管理访问令牌，并且它与 Claude Desktop、Claude.ai、ChatGPT 和您本地网络上的任何其他 MCP 客户端或配置的远程访问配合使用。 1. 将存储库添加到您的 Home Assistant 实例： [](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fhomeassistant-ai%2Fha-mcp) 如果这打开了应用商店而没有弹出添加存储库的对话框（一个 [已知的 Home Assistant 问题](https://github.com/home-assistant/my.home-assistant.io/issues/698)），请手动添加：**应用商店 → ⋮ → 存储库**，然后粘贴 `https://github.com/homeassistant-ai/ha-mcp`。 2. 从应用商店安装 **"Home Assistant MCP 服务器"** 并点击 **启动**。（Home Assistant 2026.2 将“附加组件”重命名为“应用”；在较旧的版本中，这是附加组件商店。） 3. 打开 **日志** 选项卡以查找您的唯一 MCP URL。 4. 将您的 AI 客户端连接到该 URL - **无需令牌或凭证设置**。 [完整附加组件文档 →](https://github.com/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon/DOCS.md) > ⚠️ **为每个客户端配置一种安装方法。** 自定义组件、附加组件、Docker/PyPI 和本地_stdio 是运行相同服务器的独立方法 - 选择一种并将您的 AI 客户端指向该单个 URL。在一个客户端中为同一个服务器保留两个条目（例如，本地 `uvx ha-mcp@latest` 条目与 `HOMEASSISTANT_URL` / `HOMEASSISTANT_TOKEN` 以及附加组件或组件 URL）是连接挂起的已知原因。 ### 其他安装方法 这些方法在 Home Assistant 外部运行服务器 - 对于 **容器** / **核心** 安装（无法运行附加组件）或单独的主机非常有用。[设置向导](https://homeassistant-ai.github.io/ha-mcp/setup/) 为每个客户端生成确切的客户端特定配置。 - **Docker（HTTP 服务器）：** 以 HTTP 模式运行 `ghcr.io/homeassistant-ai/ha-mcp`，指向您的 Home Assistant URL 和长期令牌，并将您的客户端连接到其机密 URL。有关完整的命令和每个客户端的配置，请参阅[设置向导](https://homeassistant-ai.github.io/ha-mcp/setup/)。 - **PyPI / uvx（HTTP 服务器）：** 以流式 HTTP 服务器的方式运行已发布的 `ha-mcp` 包，方式与上述相同。详细信息请参阅[设置向导](https://homeassistant-ai.github.io/ha-mcp/setup/)。 - **本地_stdio（不推荐）：** 在您的机器上通过_stdio 运行 ha-mcp。演示服务器部分下面的单命令安装程序使用此路径；[设置向导](https://homeassistant-ai.github.io/ha-mcp/setup/) 涵盖了将其连接到您自己的 Home Assistant。 > ⚠️ **stdio 有已知的传输问题。** stdio 传输存在连接问题，而流式 HTTP 不存在这些问题（[#1713](https://github.com/homeassistant-ai/ha-mcp/issues/1713)）。仅建议用于演示/测试 - 对于真正的设置，请使用自定义组件或上述 HTTP 方法。 <details> <summary><b>🌐 远程访问（Nabu Casa / Webhook 代理附加组件）</b></summary> > **使用 HA-MCP 自定义组件？** 您不需要此功能 - 该组件具有内置的用于远程访问的 webhook（请参见上面的 **开始使用** 快速入门）。此代理适用于 **附加组件** （它也可以通过其 `mcp_server_url` 选项前端另一个外部服务器）。 已经有 **Nabu Casa** 或另一个反向代理指向您的 Home Assistant？Webhook 代理附加组件通过您现有的设置路由 MCP 流量 - 无需单独的隧道或端口转发。 1. 安装 **MCP 服务器附加组件** （参见上文）和 **Webhook 代理** 附加组件来自同一商店 2. 启动 webhook 代理并 **重启 Home Assistant** 出现提示时 3. 从附加组件日志中复制 webhook URL： ``` MCP 服务器 URL（远程）：https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx ``` 4. 使用该 URL 配置您的 AI 客户端 有关其他远程访问方法（Cloudflare 隧道，自定义反向代理），请参阅[设置向导](https://homeassistant-ai.github.io/ha-mcp/setup/)。 [Webhook 代理文档 →](https://github.com/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon-webhook-proxy/DOCS.md) </details> ### 🧪 演示服务器（Windows / macOS / Linux） 在连接您自己的 Home Assistant 之前是否要尝试 ha-mcp？ *无需付费订阅。* 这些一键脚本设置到托管的 **stdio** 连接到演示环境，您可以在几分钟内看到它工作。每个脚本的 **连接您自己的 Home Assistant** 链接展示了如何将其指向您的实例。 <details> <summary><b>🍎 macOS</b></summary> 1. 前往 [claude.ai](https://claude.ai) 并登录（或创建免费帐户） 2. 打开 **终端** 并运行： ```sh curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh ``` 3. [下载 Claude Desktop](https://claude.ai/download) （或重启：Claude 菜单 → 退出） 4. 询问 Claude： **"您能看到我的 Home Assistant 吗？"** 您现在已连接到演示环境！ [连接您自己的 Home Assistant →](https://homeassistant-ai.github.io/ha-mcp/guide-macos/#step-6-connect-your-home-assistant) </details> <details> <summary><b>🐧 Linux</b></summary> Anthropic 不为 Linux 提供 Claude Desktop，因此请选择以下路径： **Claude Desktop** - 免费，通过社区构建： 1. 安装社区 [Linux 的 Claude Desktop](https://github.com/aaddrick/claude-desktop-debian) 构建并使用免费的 [claude.ai](https://claude.ai) 帐户登录 2. 打开 **终端** 并运行： ```sh 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`： ```sh curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code ``` 3. 启动 `claude`，运行 `/mcp` 以确认，然后询问： **"您能看到我的 Home Assistant 吗？"** [完整 Linux 指南 →](https://homeassistant-ai.github.io/ha-mcp/guide-linux/) </details> <details> <summary><b>🪟 Windows</b></summary> 1. 前往 [claude.ai](https://claude.ai) 并登录（或创建免费帐户） 2. 打开 **Windows PowerShell** （从开始菜单）并运行： ```powershell irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex ``` 3. [下载 Claude Desktop](https://claude.ai/download) （或重启：文件 → 退出） 4. 询问 Claude： **"您能看到我的 Home Assistant 吗？"** 您现在已连接到演示环境！ [连接您自己的 Home Assistant →](https://homeassistant-ai.github.io/ha-mcp/guide-windows/#step-6-connect-your-home-assistant) </details> ### 🧙 适用于 15+ 个客户端的设置向导 **Claude Code、Gemini CLI、ChatGPT、Open WebUI、VSCode、Cursor 等。** <p> <a href="https://homeassistant-ai.github.io/ha-mcp/setup/"><img src="https://img.shields.io/badge/Open_Setup_Wizard-4A90D9?style=for-the-badge" alt="打开设置向导" height="40"></a> </p> 遇到问题？查看 **[FAQ 和故障排除](https://homeassistant-ai.github.io/ha-mcp/faq/)** --- ## 💬 您可以用它做什么？ 只需自然地与 Claude 交谈。以下是一些真实的例子： | 您说的话 | 会发生什么 | |---------|--------------| | *"创建一个在日落时打开门廊灯的自动化程序"* | 使用正确的触发器和操作创建自动化程序 | | *"在我的仪表板上添加一个天气卡"* | 更新您的 Lovelace 仪表板以添加新卡 | | *"运动传感器自动化程序不起作用，调试它"* | 分析执行轨迹，识别问题，建议修复 | | *"使我的早晨例行自动化程序也打开咖啡机"* | 读取现有的自动化程序，添加新操作，更新它 | | *"创建一个脚本，设置电影模式：调暗灯光，关闭窗帘，打开电视"* | 创建一个具有操作序列的可重用脚本 | 花更少的时间配置，多花时间享受您的智能家居。 --- ## ✨ 功能 | 类别 | 功能 | |----------|--------------| | **🔍 搜索** | 模糊实体搜索，深度配置搜索，系统概览 | | **🏠 控制** | 任意服务，批量设备控制，实时状态 | | **🔧 管理** | 自动化程序，脚本，帮助程序，仪表板，区域，区域，组，日历，蓝图 | | **📊 监控** | 历史记录，统计数据，摄像头快照，自动化跟踪，ZHA 设备 | | **💾 系统** | 备份/恢复，更新，附加组件，设备注册表 | | **🔒 安全** | 只读模式启用，每个工具启用/禁用，工具安全策略（用户批准），自动编辑备份 | <details> <!-- TOOLS_TABLE_START --> <summary><b>完整工具列表（85 个工具）</b></summary> | 类别 | 工具 | |----------|-------| | **附加组件** | `ha_get_addon`，`ha_manage_addon` | | **区域和楼层** | `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_get_blueprint`，`ha_import_blueprint` | | **日历** | `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_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_enabled` | | **标签和类别** | `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_set_yaml` *(beta)*，`ha_manage_backup`，`ha_manage_custom_tool` *(beta)*，`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_install_mcp_tools` *(beta)*，`ha_report_issue` | | **区域** | `ha_get_zone`，`ha_remove_zone`，`ha_set_zone` | <!-- TOOLS_TABLE_END --> </details> --- ## 🆚 ha-mcp vs. Home Assistant 自带 MCP 服务器 Home Assistant 自带了 [MCP 服务器集成](https://www.home-assistant.io/integrations/mcp_server/)。 它是基于 **Assist** 管道构建的，因此连接的 MCP 客户端可以读取和控制您已暴露给 Assist 的实体，并运行 Assist 可以理解的意图 — 对于已经暴露的设备的语音控制非常方便。 ha-mcp 是一个独立的服务器，旨在 **配置、构建和调试** 您的智能家居，而不仅仅是控制它。 在设备控制之上，它添加了内置集成不具备的功能： | 功能 | 自带 MCP 服务器 | ha-mcp | |------------|:-------------------:|:------:| | 控制暴露的设备，查询状态 | 是 | 是 | | 实体范围 | 仅限暴露给 Assist 的实体 | Home Assistant 中的所有内容 | | 创建/编辑自动化、脚本、场景 | 否 | 是 | | 构建和编辑仪表盘 | 否 | 是 | | 从跟踪调试自动化，读取历史记录和日志 | 否 | 是 | | 管理助手、区域、区域、标签、组 | 否 | 是 | | 备份、附加组件、HACS、设备和实体注册表 | 否 | 是 | **经验法则：** 对于您已经暴露的设备的语音控制，使用内置集成；当您想要一个 AI 助手，还可以构建和维护您的 Home Assistant 设置时，使用 ha-mcp。 --- ## 🔌 自定义组件（ha_mcp_tools）— 文件和 YAML 服务 **HA-MCP 自定义组件** 还提供了一组特权工具，这些工具是标准 Home Assistant API 无法提供的：文件系统访问和 YAML 配置编辑。 （同一个组件在进程中运行完整的服务器 — 这是在 **开始使用** 部分推荐的安装方式。）它的 **HA MCP Tools** 服务入口使以下工具可用。 **需要该组件的工具：** | 工具 | 描述 | |------|-------------| | `ha_config_set_yaml` *(测试版)* | 安全地添加、替换或删除 `configuration.yaml` 和软件包文件中的顶级 YAML 键（自动备份、验证和配置检查） | | `ha_list_files` *(测试版)* | 列出允许目录中的文件 | | `ha_read_file` *(测试版)* | 从允许的路径读取文件（配置文件 YAML、日志和允许的目录） | | `ha_write_file` *(测试版)* | 将文件写入允许的目录 | | `ha_delete_file` *(测试版)* | 从允许的目录中删除文件 | 所有其他工具无需该组件即可使用。 如果缺少该组件，这五个工具将返回错误并提供安装说明。 这些工具还需要测试版功能标志。 有关如何启用它们，请参阅 **[测试版功能](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/beta.md)**，包括 `ENABLE_BETA_FEATURES` 主标志，必须启用后，文件系统/YAML 子标志才会生效。 ### 安装 从同一个 **HA-MCP 自定义组件** 安装 **HA MCP Tools** 服务入口： [](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp-integration&category=integration) 手动添加：打开 **HACS** > **集成** > 三点菜单 > **自定义仓库** > 添加 `https://github.com/homeassistant-ai/ha-mcp-integration`（类别：集成）> **下载**。 或者，将 `custom_components/ha_mcp_tools/` 从此仓库复制到您的 HA `config/custom_components/` 目录中。 安装后，重启 Home Assistant，然后打开 **设置** > **设备和服务** > **添加集成**，搜索 **HA-MCP 自定义组件**，并添加 **HA MCP Tools** 服务入口。 要通过此同一组件在进程中运行完整的 ha-mcp 服务器，请参阅顶部 **开始使用** 部分和 [完整的进程内服务器文档 →](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/in-process-server.md)。 --- ## 🧠 使用代理技能获得更好的结果 该服务器为您的 AI 代理提供了控制 Home Assistant 的工具。 为了获得更好的配置，请将其与 [Home Assistant 代理技能](https://github.com/homeassistant-ai/skills) 配对使用 — 领域知识，教导代理 Home Assistant 的最佳实践。 MCP 服务器可以创建自动化、助手和仪表盘，但它对如何构建它们没有意见。 没有领域知识，代理往往会过度依赖模板，选择错误的助手类型，或生成难以维护的自动化。 技能填补了这一空白：本地构造而非 Jinja2 变通方法，正确的助手选择，安全的重构工作流和正确的自动化模式使用。 ### 捆绑技能（内置） `homeassistant-ai/skills` 中的技能被捆绑并作为 [MCP 资源](https://modelcontextprotocol.io/docs/concepts/resources) 通过 `skill://` URI 提供。 任何支持资源的 MCP 客户端都可以自动发现它们 — 无需手动安装。 对于仅限工具的客户端（例如 claude.ai），相同的技能可以通过多态 `ha_get_skill_guide` 工具访问 — 调用它时不带参数以列出捆绑技能，带 `skill` 参数以列出其文件，或带 `skill` + `file` 以读取内容。 资源不会自动注入到上下文中 — 客户端必须显式请求它们，因此空闲上下文成本仅为元数据列表。 `ha_get_skill_guide` 是一个必填工具：目录始终会公开它（无法禁用），因此仅限工具的客户端永远不会看到沉默的技能表面。 技能仍然可以手动安装，供喜欢本地技能文件的客户端使用 — 有关说明，请参阅 [技能仓库](https://github.com/homeassistant-ai/skills)。 --- ## 🔍 AI 代理的工具发现 默认情况下，完整的工具目录（约 84 个工具）通过标准 MCP `tools/list` 响应列出给客户端。 具有延迟/按需工具加载的客户端（Claude Sonnet，Claude Opus）可以很好地处理这一点 — 工具仅在需要时被拉入上下文，因此空闲上下文成本几乎为零。 对于没有延迟工具支持的模型 — Claude Haiku，Gemini，ChatGPT OpenAI 兼容的本地模型，较小的开放权重模型 — 预先列出完整的工具目录会增加很多空闲上下文，可能会让较小的模型不堪重负。 为了解决这个问题，服务器配备了 **基于搜索的发现模式**，基于 FastMCP 的 BM25 搜索转换。 ### 较小的或本地的 LLMs（Ollama 等） 如果您的模型无法看到工具或 Home Assistant，可能是因为它一次收到整个工具目录并难以应对。 建议尝试以下方法： - **启用工具搜索** (`ENABLE_TOOL_SEARCH=true`，或下面的附加组件选项）。 而不是预先列出每个工具，服务器将目录延迟到搜索接口后面，以便模型仅在需要时拉入工具。 - **将模型的上下文窗口提高到默认值以上。** 本地运行时会带有小默认值（Ollama 的 `num_ctx` 就是一个例子），无法容纳大型工具集加上对话 — 将其增加到远超默认值。 ### 启用基于搜索的发现 设置 `ENABLE_TOOL_SEARCH=true`（或在 HA 附加组件中切换选项）。 完整的目录被四个入口点和一小部分始终可见的“固定”工具（ha_search_entities，ha_get_overview，ha_restart 等）取代。 所有工具仍然可以直接按名称调用： | 工具 | 用途 | |------|---------| | `ha_search_tools` | 跨所有工具的 BM25 关键词搜索。 返回名称、描述、参数和注释 (`readOnlyHint` / `destructiveHint`) 以便代理选择正确的工具。 | | `ha_call_read_tool` | 按名称执行 `readOnlyHint` 工具。 安全 — 客户端可以自动批准。 | | `ha_call_write_tool` | 执行创建或更新数据的写入工具。 | | `ha_call_delete_tool` | 执行删除 / 删除数据的工具。 | 代理分割让 MCP 客户端可以对不同类别应用不同的权限策略（例如，自动批准读取，提示写入，确认删除）而无需解析工具文档字符串。 | 设置 | 默认值 | 描述 | |---------|---------|-------------| | `ENABLE_TOOL_SEARCH` | `false` | 用基于搜索的发现替换完整的工具目录（工具延迟到按需搜索）。 | | `TOOL_SEARCH_MAX_RESULTS` | `5` | `ha_search_tools` 返回的最大结果数（范围 2–10）。 | | `PINNED_TOOLS` | 空 | 逗号分隔的始终可见的工具名称。 Web 设置 UI 是管理此设置的 primary 方式。 | ### 何时启用 - **Claude Haiku，OpenAI 兼容的本地模型，Gemini，ChatGPT 或任何没有原生延迟工具支持的模型** — 大幅度节省空闲上下文。 - 限制总工具数量的 MCP 客户端（某些客户端限制在 100）— 显示最小化的一组（~10 个工具）而不是 84 个。 - **成本敏感的部署** — 每个回合的空闲 token 减少。 如果使用 Claude Sonnet/Opus 或任何具有延迟工具加载的客户端，请关闭它；完整的目录在那里没有空闲成本，直接调用会跳过搜索步骤。 如果您选择使用我们的工具搜索，则应禁用原生 Claude Opus/Sonnet 工具搜索，也称为延迟工具，在设置中。 > 🔄 **刷新客户端的工具列表，然后更改此设置（或任何）设置。** 切换 `ENABLE_TOOL_SEARCH`（或更改固定的/禁用的工具，读取仅限模式等）会更改服务器公开的工具，但您的 AI 客户端会继续提供其 **缓存** 的工具列表，直到它重新获取。 重启附加组件或 Home Assistant **不会** 刷新客户端 — 断开连接或在客户端中刷新 MCP 服务器（例如，在 ChatGPT 中重新添加/刷新连接器，或关闭并重新打开 Claude Desktop）。 如果您跳过此步骤，显示为可用的工具将被调用时返回 `Unknown tool`。 对于 HA 附加组件，相同的选项在 [`homeassistant-addon/DOCS.md`](https://github.com/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon/DOCS.md#enable_tool_search) 中有文档记录，以及附加组件中的设置 UI，用于细粒度工具启用/禁用/固定。 --- ## 🧪 开发频道 想要提前访问新功能和修复吗？ 开发版（`.devN`）在每次推送到主分支时发布。 **[开发频道文档](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/dev-channel.md)** — pip/uvx、Docker 和 Home Assistant 附加组件的说明。 --- ## 🤝 贡献 有关开发设置、测试说明和贡献指南，请参阅 **[CONTRIBUTING.md](https://github.com/homeassistant-ai/ha-mcp/blob/master/CONTRIBUTING.md)**。 有关综合测试文档，请参阅 **[tests/README.md](https://github.com/homeassistant-ai/ha-mcp/blob/master/tests/README.md)**。 --- ## 🔒 隐私 Ha-mcp 在您的机器上 **本地运行**。 您的智能家居数据保留在您的网络上。 - **目前没有遥测** — 匿名使用统计数据是计划中的未来功能（截至 2026 年 6 月）；当它上线时，它将遵循您的 Home Assistant 分析/遥测设置（您可以覆盖），并在发布说明和 Web 设置 UI 中至少提前一个月公布。 - **不收集个人数据** — 我们永远不会收集实体名称、配置或设备数据。 - **用户控制的错误报告** — 仅在您明确批准时发送。 有关详细信息，请参阅我们的 [隐私政策](https://github.com/homeassistant-ai/ha-mcp/blob/master/PRIVACY.md)。 --- ## 📄 许可证 该项目在 MIT 许可证下许可 — 有关详细信息，请参阅 [LICENSE](https://github.com/homeassistant-ai/ha-mcp/blob/master/LICENSE) 文件。 --- ## 🙏 致谢 - **[Home Assistant](https://home-assistant.io/)**: 优秀的智能家居平台 (!) - **[FastMCP](https://github.com/jlowin/fastmcp)**: 优秀的 MCP 服务器框架 - **[Model Context Protocol](https://modelcontextprotocol.io/)**: 标准化的 AI 应用程序通信 - **[Claude Code](https://github.com/anthropics/claude-code)**: AI 驱动的编码助手 - **[PolicyLayer](https://policylayer.com/)**: 参数路径谓词 DSL 形状 (`args.domain in [...]` with `eq`/`in`/`regex`/`contains`/`exists`/...) 启发了每个工具的审批规则模式 (#966)。 ## 👥 贡献者 ### 维护者 - **[@julienld](https://github.com/julienld)** — 项目创建者。 - **[@sergeykad](https://github.com/sergeykad)** — 核心维护者。 - **[@kingpanther13](https://github.com/kingpanther13)** — 核心维护者。 - **[@Patch76](https://github.com/Patch76)** — 核心维护者。 ### 贡献者 - **[bigeric08](https://github.com/bigeric08)** — 为协议版本 2025-11-25 的支持添加明确的 `mcp` 依赖。 - **[airlabno](https://github.com/airlabno)** — 在调度时间块中支持 `data` 字段。 - **[ryphez](https://github.com/ryphez)** — Codex Desktop UI MCP 快速设置指南。 - **[Danm72](https://github.com/Danm72)** — 用于管理实体属性的实体注册工具（`ha_set_entity`，`ha_get_entity`）。 - **[Raygooo](https://github.com/Raygooo)** — SOCKS 代理支持。 - **[cj-elevate](https://github.com/cj-elevate)** — 集成和实体管理工具（启用/禁用/删除）；人员/区域/标签配置存储路由。 - **[maxperron](https://github.com/maxperron)** — Beta 测试。 - **[kingbear2](https://github.com/kingbear2)** — Windows UV 设置指南。 - **[konradwalsh](https://github.com/konradwalsh)** — 通过 [GitHub Sponsors](https://github.com/sponsors/julienld) 提供经济支持。谢谢！ ☕ - **[knowald](https://github.com/knowald)** — 在 `ha_get_system_overview` 中通过设备注册进行区域解析，适用于通过其父设备分配的实体。通过 [GitHub Sponsors](https://github.com/sponsors/julienld) 提供经济支持。谢谢！ ☕ - **[zorrobyte](https://github.com/zorrobyte)** — OAuth 模式下的每个客户端 WebSocket 凭证，修复 WebSocket 工具故障。 - **[deanbenson](https://github.com/deanbenson)** — 修复具有许多自动化的大型 Home Assistant 实例上的 `ha_deep_search` 超时。 - **[saphid](https://github.com/saphid)** — 配置条目选项流工具（初始设计，#590）。 - **[adraguidev](https://github.com/adraguidev)** — 修复用于组帮助程序的基于菜单的配置条目流 (#647)。 - **[transportrefer](https://github.com/transportrefer)** — 集成选项检查 (`ha_get_integration` 模式支持，#689)。 - **[teh-hippo](https://github.com/teh-hippo)** — 修复蓝图导入缺少保存步骤。 - **[smenzer](https://github.com/smenzer)** — 文档修复。 - **[The-Greg-O](https://github.com/The-Greg-O)** — 配置条目删除的 REST API。 - **[restriction](https://github.com/restriction)** — 责任披露：python_transform 沙箱缺少调用目标验证。 - **[lcrostarosa](https://github.com/lcrostarosa)** — 诊断和健康监测工具概念 (#675)，激发系统/错误日志，修复和 ZHA 无线电指标集成。 - **[roysha1](https://github.com/roysha1)** — 安装向导中的 Copilot CLI 支持；用实际品牌图标替换占位符徽标 SVG，显示在文档站点上。 - **[teancom](https://github.com/teancom)** — 修复插件统计端点 (`/addons/{slug}/stats`)。 - **[TomasDJo](https://github.com/TomasDJo)** — 自动化、脚本和场景的类别支持。 - **[bzelch](https://github.com/bzelch)** — 自动化和脚本的 `python_transform` 支持。 - **[gcormier](https://github.com/gcormier)** — Windows 安装程序改进：删除未使用的变量并修复安装后终端关闭。 - **[ekobres](https://github.com/ekobres)** — 插件配置中 `HAMCP_ENABLE_FILESYSTEM_TOOLS` 和 `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION` 的功能标志，在源和文档中添加 Beta 标签。 - **[w3z315](https://github.com/w3z315)** — 通过 [GitHub Sponsors](https://github.com/sponsors/julienld) 提供经济支持。谢谢！ ☕ - **[griffinmartin](https://github.com/griffinmartin)** — 在设置向导中添加 OpenCode（由 Anomaly 提供）作为可选择的 AI 客户端，支持 stdio 和可流式 HTTP。 - **[hhopke](https://github.com/hhopke)** — 修复插件 API 调用以通过 HA Core ingress 代理而不是直接容器连接路由，修复插件安装中的 `ha_manage_addon` 代理模式。 - **[tomwilkie](https://github.com/tomwilkie)** — JMESPath 中间件探索 (#1147)，其审查时间令牌测量数据为 #1199 和 #1225 的设计提供了参考。 - **[SealKan](https://github.com/SealKan)** — 六个读取量大的工具上的 `fields=`/`attribute_keys=` 投影 (#1225)，`ha_call_event` 工具 (#1239)，仪表盘列表助手重构 (#1207)，`for:`-field 时长数学检测器在最佳实践检查器中 (#1264)，跨重启的持久 DCR OAuth 客户端注册 (#1265)，以及问题分类提示令牌预算 (#1522)。 - **[KarelTestSpecial](https://github.com/KarelTestSpecial)** — 缓存 YAML 实例以防止批量编辑期间的 CPU 峰值 (#1371)。 - **[corgan2222](https://github.com/corgan2222)** — 自定义集成的 HA 品牌资产 (#1317)。 - **[drseanwing](https://github.com/drseanwing)** — 在长时间运行的工具中通过 FastMCP `Context` 发出进度 (#1124)；工具发现/分类搜索文档 (#1123)。 - **[fnordpig](https://github.com/fnordpig)** — 配置子条目支持 (#1393) 和 Assist 管道管理工具 (#1392)。 - **[paul43210](https://github.com/paul43210)** — `ha_manage_addon` 中的 `array_patch` 模式，用于原子 GET-修改-POST (#1063)。 - **[L1AD](https://github.com/L1AD)** — 提交 #966 提出工具安全策略；指出 PolicyLayer 的 MCP 安全工作是激发谓词 DSL 形状的先前艺术。 - **[nightcityblade](https://github.com/nightcityblade)** — 在 HA 2026.6 使以前的先进选项默认可用后，更新陈旧的 Home Assistant 高级模式引用 (#1533)。 - **[emmelutzer](https://github.com/emmelutzer)** — 通过 [GitHub Sponsors](https://github.com/sponsors/julienld) 提供经济支持。谢谢！ ☕ - **[pkkr](https://github.com/pkkr)** — `ha_knx_get_project` 工具，从上传的 ETS 项目文件中公开 KNX 组地址。 - **[cbowns](https://github.com/cbowns)** — 修复设置.astro Codex CLI 文档中的不一致连字符。 - **[Shaan-alpha](https://github.com/Shaan-alpha)** — 将 `ha_restart` 已知良好的错误模式扩展到涵盖反向代理的 502/503 响应。 - **[rebelancap](https://github.com/rebelancap)** — 修复 `add_timezone_metadata` 中的 UTC 到本地时区的转换。 - **[saevras](https://github.com/saevras)** — 修复蓝图导入 E2E 测试，以使用本地 URL 代替主机到容器的网络连接。 - **[jasonjhofmann](https://github.com/jasonjhofmann)** — 通过 `rrule` 支持在 `ha_config_set_calendar_event` 中实现定期日历事件。 - **[vpciii](https://github.com/vpciii)** — 在字典/列表工具参数上强制 JSON 编码的字符串。 - **[pburtchaell](https://github.com/pburtchaell)** — 通过 [GitHub Sponsors](https://github.com/sponsors/julienld) 提供经济支持。谢谢！ ☕ ## 💬 社区 - **[GitHub 讨论](https://github.com/homeassistant-ai/ha-mcp/discussions)** — 提问，分享想法 - **[问题跟踪器](https://github.com/homeassistant-ai/ha-mcp/issues)** — 报告错误，请求功能，或建议工具行为改进 ## ⭐ 星历史 [](https://star-history.com/#homeassistant-ai/ha-mcp&Date)