项目简介

Home Assistant AI 上下文服务器（HA-MCP）是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在作为大语言模型（LLM）与 Home Assistant 智能家居平台之间的桥梁。它允许 LLM 客户端通过自然语言理解和操作 Home Assistant 中的设备、自动化和配置，从而实现智能家居的AI控制和管理。

主要功能点

智能发现、搜索与查询：
- 模糊实体搜索：支持容错的实体名称模糊搜索。
- 深度配置搜索：在自动化、脚本和辅助实体配置中进行关键词搜索。
- AI 优化系统概览：提供实体数量、区域、设备状态等全面的系统分析。
- 模板评估：评估 Home Assistant 模板，用于动态数据处理。
- 日志数据访问：查询日志条目，支持日期和实体过滤。
设备与服务控制：
- 通用服务控制：执行任何 Home Assistant 服务，支持完整的参数。
- 实时状态访问：获取详细的实体状态，包括属性、时间戳和上下文信息。
- 批量设备控制：支持通过 WebSocket 验证同时控制多个设备。
配置管理：
- 自动化与脚本管理：创建、修改、删除、启用/禁用及触发 Home Assistant 自动化和脚本。
- 辅助实体管理：创建、修改、删除 'input_boolean'、'input_number'、'input_select'、'input_text'、'input_datetime' 和 'input_button' 等辅助实体。
安全与维护：
- 备份与恢复：创建快速本地备份（不包含数据库）并支持安全恢复。

安装步骤

HA-MCP 服务器提供了多种安装方式，推荐使用 Home Assistant 插件或 Docker 容器方式。

方法一：Home Assistant 插件（推荐）

适用于运行 Home Assistant OS 的用户，提供最简便的安装体验。

添加仓库：在 Home Assistant Supervisor 的“插件商店”中，通过点击按钮或手动添加以下仓库 URL：

https://github.com/homeassistant-ai/ha-mcp

安装插件：在插件商店中找到名为“Home Assistant MCP Server”的插件，点击安装并启动。
获取访问URL：插件启动后，Home Assistant UI 会显示 MCP 服务器的访问 URL，其中包含一个动态生成的秘密路径（例如：'http://<home-assistant-ip>:9583/private_your_secret_string'）。请务必复制此完整 URL，LLM 客户端连接时需要使用。

方法二：Docker 容器

适用于 Home Assistant Container 或 Docker 环境。

获取长期访问令牌：在 Home Assistant UI 中，前往“你的个人资料”->“安全”->“长期访问令牌”创建并复制一个令牌。

启动容器：使用 Docker 命令或 'docker-compose.yml' 启动 HA-MCP 容器。以下是一个使用 'docker run' 的示例，LLM 客户端会通过其进程管理功能自动启动和停止此容器：

# LLM 客户端在内部执行此命令来启动 MCP 服务器进程
docker run --rm \
-e HOMEASSISTANT_URL=http://homeassistant.local:8123 \
-e HOMEASSISTANT_TOKEN=your_long_lived_token \
ghcr.io/homeassistant-ai/ha-mcp:latest

这将启动一个临时的 Docker 容器，并将其作为 LLM 客户端的 MCP 服务器。

服务器配置（MCP客户端侧）

MCP 客户端需要配置如何启动和连接 HA-MCP 服务器。以下是 LLM 客户端配置文件的 JSON 格式示例及其参数说明：

场景一：LLM 客户端直接启动 Docker 容器

适用于 Claude Desktop 或任何支持 'mcp.json' 格式的客户端，例如在 'mcp.json' 或 'claude_desktop_config.json' 中添加：

{
  "mcpServers": {
    "home-assistant": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-e", "HOMEASSISTANT_URL=http://homeassistant.local:8123",
        "-e", "HOMEASSISTANT_TOKEN=your_long_lived_token",
        "ghcr.io/homeassistant-ai/ha-mcp:latest"
      ],
      "env": {
        "MCP_SERVER_NAME": "ha-mcp",
        "MCP_SERVER_VERSION": "3.1.6"
      }
    }
  }
}

参数说明：

'"home-assistant"': 这是您为该 MCP 服务器实例定义的名称，可自定义。
'"command"': 指定用于启动 MCP 服务器的可执行程序，此处为 '"docker"'。
'"args"': 传递给 'command' 的参数列表。
- '"run"': Docker 命令，用于运行容器。
- '"--rm"': 容器退出时自动删除。
- '"-e HOMEASSISTANT_URL=..."': 设置 'HOMEASSISTANT_URL' 环境变量，指向您的 Home Assistant 实例地址。例如：'http://homeassistant.local:8123'。
- '"-e HOMEASSISTANT_TOKEN=..."': 设置 'HOMEASSISTANT_TOKEN' 环境变量，用于 Home Assistant API 认证的长期访问令牌。请替换为您的实际令牌。
- '"ghcr.io/homeassistant-ai/ha-mcp:latest"': 指定要运行的 Docker 镜像名称及标签。
'"env"': 可选，用于设置 MCP 服务器内部使用的环境变量，如服务器名称和版本，通常无需修改。

场景二：LLM 客户端通过 HTTP/HTTPS 连接已运行的 HA-MCP 服务器（例如 Home Assistant 插件或 Docker Compose 部署）

如果 HA-MCP 服务器已独立运行（例如作为 Home Assistant 插件或通过 Docker Compose 部署并暴露了 HTTP/HTTPS 接口），LLM 客户端的配置将更简单，只需提供服务器的访问 URL。

例如，对于 Home Assistant 插件，您会得到一个类似 'http://<home-assistant-ip>:9583/private_your_secret_string' 的 URL。LLM 客户端的配置将如下所示（具体格式取决于 LLM 客户端，此处为概念性示例）：

{
  "mcpServers": {
    "home-assistant-web": {
      "transport": "http",
      "url": "http://<home-assistant-ip>:9583/private_your_secret_string"
    }
  }
}