关键词

智能家居Home AssistantLLMClaude自动化设备控制情境感知

项目简介

Hass-MCP (Home Assistant Model Context Protocol) 是一个基于 Model Context Protocol (MCP) 构建的服务器，它允许大型语言模型 (LLM)，如 Claude，直接与您的 Home Assistant 智能家居系统进行交互。通过 Hass-MCP，LLM 可以查询设备状态、控制智能设备、获取智能家居摘要信息，甚至辅助用户进行自动化配置和故障排除。

主要功能点

  • 实体管理：查询 Home Assistant 中设备和传感器的状态，控制灯光、开关等实体，并支持实体搜索。
  • 领域摘要：获取 Home Assistant 各个领域（如灯光、传感器）的设备类型和状态的概览信息。
  • 自动化支持：列出和控制 Home Assistant 中配置的自动化规则。
  • 引导式对话：通过预设 Prompt 模板，引导 LLM 与用户进行关于智能家居任务的对话，例如创建自动化。
  • 智能搜索：根据名称、类型或状态搜索 Home Assistant 实体。
  • Token 效率：采用精简的 JSON 响应格式，最大限度地减少 Token 消耗。

安装步骤

  1. 前提条件：

    • 已安装并运行 Home Assistant，并生成了长期访问令牌 (Long-Lived Access Token)。
    • 满足以下任一条件：
      • 已安装 Docker (推荐)。
      • 已安装 Python 3.13+ 及 uv (Python 包管理器)。

  2. Docker 安装 (推荐)：

    • 拉取 Docker 镜像： 
      docker pull voska/hass-mcp:latest

服务器配置

要将 Hass-MCP 服务器连接到 MCP 客户端（例如 Claude Desktop），您需要在 MCP 客户端中配置服务器的启动命令和参数。以下是针对 Claude Desktop 的配置示例，其他 MCP 客户端的配置方式类似。

在 Claude Desktop 的 'claude_desktop_config.json' 配置文件 (Settings -> Developer -> Edit Config) 中，添加以下 'mcpServers' 配置：

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",  //  Home Assistant 的 URL，例如 http://your_homeassistant_ip:8123 或 http://your_domain.com
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"  // 您的 Home Assistant 长期访问令牌，请替换为实际令牌
      }
    }
  }
}

配置参数说明：

  • server name: 'hass-mcp' - 服务器名称，在 MCP 客户端中用于标识和选择该服务器。
  • command: 'docker' - 启动 MCP 服务器的命令，这里使用 Docker 运行镜像。
  • args: Docker 运行参数列表：
    • 'run -i --rm': Docker 运行命令，'-i' 表示保持 STDIN 开放，'--rm' 表示容器退出后自动删除。
    • '-e HA_URL': 设置环境变量 'HA_URL'，用于指定 Home Assistant 的访问地址。
    • '-e HA_TOKEN': 设置环境变量 'HA_TOKEN'，用于传递 Home Assistant 的长期访问令牌。
    • 'voska/hass-mcp': 要运行的 Docker 镜像名称。
  • env: 环境变量配置：
    • 'HA_URL': 请务必根据您的 Home Assistant 实际地址进行修改。如果 Home Assistant 运行在同一机器的 Docker 中，可能需要使用 'http://host.docker.internal:8123' (Docker Desktop on Mac/Windows) 或宿主机的 IP 地址。
    • 'HA_TOKEN': 请务必替换为您的 Home Assistant 长期访问令牌。

保存配置文件并重启 Claude Desktop 后，"Hass-MCP" 工具将出现在 Claude Desktop 的工具菜单中。

基本使用方法

成功配置 Hass-MCP 后，您可以在支持 MCP 协议的 LLM 客户端中使用以下示例指令与您的 Home Assistant 进行交互：

  • 查询实体状态: "What's the current state of my living room lights?" (我的客厅灯现在是什么状态？)
  • 控制设备: "Turn off all the lights in the kitchen" (关掉厨房所有的灯)
  • 查询传感器: "List all my sensors that contain temperature data" (列出所有包含温度数据的传感器)
  • 获取领域摘要: "Give me a summary of my climate entities" (给我一个气候实体的摘要)
  • 创建自动化: "Create an automation that turns on the lights at sunset" (创建一个在日落时打开灯的自动化)
  • 故障排除: "Help me troubleshoot why my bedroom motion sensor automation isn't working" (帮我排除卧室 motion sensor 自动化无法工作的问题)
  • 实体搜索: "Search for entities related to my living room" (搜索与我的客厅相关的实体)

更多详细用法和可用工具、Prompt 模板请参考仓库 README 文档。

信息

分类

桌面与硬件

访问项目