使用说明

项目简介

Home Assistant MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，它将 Home Assistant 智能家居平台的功能暴露给大型语言模型 (LLM)。通过此服务器，LLM 可以安全、可扩展地与 Home Assistant 集成，实现智能家居设备的控制和状态查询。

主要功能点

设备控制: 支持控制多种 Home Assistant 域的设备，包括：
- 灯光 (Lights)：开关灯、调节亮度
- 气候 (Climate)：调节温度、控制 HVAC 模式
- 门锁 (Locks)：锁定/解锁门锁
- 安防控制面板 (Alarm Control Panel)：布防/撤防安防系统
- 加湿器 (Humidifier)：调节湿度
工具集成: 将 Home Assistant 的各项控制功能封装为 MCP 工具 (Tools)，方便 LLM 调用。
Prompt支持: 为每个设备域提供 Prompt 模板 (Prompts)，优化 LLM 的交互体验 (仓库中仅提及，未见具体Prompt模板定义)。
标准化接口: 遵循 MCP 协议，提供标准的 JSON-RPC 接口与客户端通信。

安装步骤

安装 Home Assistant: 如果尚未安装，请先安装 Home Assistant 并获取一个长期访问令牌 (Long-Lived Access Token)。参考 Home Assistant 入门指南。
克隆仓库: 将 GitHub 仓库 'MCP-Mirror/miguelg719_home-assistant-mcp' 克隆到本地。
配置环境变量:
- 在项目根目录下创建 '.env' 文件。
- 在 '.env' 文件中填入你的 Home Assistant 长期访问令牌 (HOMEASSISTANT_TOKEN) 和 Base URL (HOMEASSISTANT_BASE_URL)，例如：
```
HOMEASSISTANT_TOKEN=你的长期访问令牌
HOMEASSISTANT_BASE_URL=http://homeassistant.local:8123
```
  注意: 请将 '你的长期访问令牌' 替换为你在 Home Assistant 中生成的长期访问令牌，'http://homeassistant.local:8123' 替换为你的 Home Assistant 实例的 URL。
安装依赖: 在项目根目录下运行 'uv sync' 命令安装项目依赖。

服务器配置

MCP 服务器需要配置在 MCP 客户端中才能使用。以 Claude 客户端为例，需要在 Claude 的配置文件 'claude_desktop_config.json' 中添加 MCP 服务器的配置信息。

开发/未发布服务器配置 (Development/Unpublished Servers Configuration):

"mcpServers": {
  "home-assistant-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/home-assistant-server",
      "run",
      "src/home_assistant_mcp/server.py"
    ]
  }
}

已发布服务器配置 (Published Servers Configuration):

"mcpServers": {
  "home-assistant-server": {
    "command": "uvx",
    "args": [
      "home-assistant-server"
    ]
  }
}

配置参数说明:

'"home-assistant-server"': 服务器名称，可以自定义。
'"command": "uv"' (或 '"uvx"'): 启动服务器的命令，这里使用 'uv' 运行 Python 脚本 (或 'uvx' 运行已发布的包)。
'"args"': 命令参数，
- 开发模式下 ( '"command": "uv"' )：
  - '"--directory"': 指定项目根目录的路径，请将 '"/path/to/home-assistant-server"' 替换为你的项目实际路径。
  - '"run"': uv 的运行子命令。
  - '"src/home_assistant_mcp/server.py"': MCP 服务器的入口 Python 脚本路径。
- 发布模式下 ( '"command": "uvx"' )：
  - '"home-assistant-server"': 已发布的 Python 包名称 (需要先执行 "Building and Publishing" 步骤)。

基本使用方法

启动服务器: 根据选择的配置方式，在终端中运行相应的命令启动 MCP 服务器。例如，在项目根目录下，使用开发模式配置时，可以运行 'uv run src/home_assistant_mcp/server.py'。
配置 MCP 客户端: 将上述服务器配置信息添加到 MCP 客户端的配置文件中 (例如 Claude 的 'claude_desktop_config.json')，确保客户端能够连接到 MCP 服务器。
通过 LLM 客户端交互: 使用支持 MCP 协议的 LLM 客户端 (如 Claude) 向 LLM 发出指令，LLM 将通过 MCP 服务器调用 Home Assistant 的工具来控制智能家居设备。例如，你可以对 Claude 说 "打开客厅的灯" 或 "将卧室温度设置为 20 度"。

关键词