Home Assistant MCP Server 使用说明

项目简介

Home Assistant MCP Server 是一个基于 Model Context Protocol (MCP) 构建的应用后端，它桥接了 Home Assistant 智能家居系统和大型语言模型 (LLM) 客户端。通过此服务器，LLM 应用能够以标准化的方式与 Home Assistant 交互，实现智能家居设备的控制和状态查询。

主要功能点

设备控制: 支持控制多种 Home Assistant 域的设备，包括灯光、气候设备（如空调、暖气）、锁具、报警控制面板和加湿器等。
工具集成: 将 Home Assistant 的控制功能封装为 MCP 工具 (Tools)，LLM 客户端可以通过调用这些工具来控制智能家居设备。例如，可以使用 'light-turn_on' 工具打开灯，使用 'climate-set_temperature' 工具设置空调温度。
Prompt支持: 为每个设备域提供 Prompt 模板 (Prompts)，虽然仓库中只提供了示例 Prompt，但表明具备 Prompt 管理能力，可以根据不同场景定制 LLM 交互模式。（仓库提供的代码示例中只包含 Prompt 的定义，实际服务器代码中未集成 Prompt 的处理逻辑，但根据 README 描述推测未来可能支持）
易于集成: 使用标准的 MCP 协议和 JSON-RPC 通信，可以方便地与任何支持 MCP 协议的 LLM 客户端集成，例如 Claude。
可扩展性: 通过模块化的服务设计，易于扩展支持更多的 Home Assistant 设备域和服务。

安装步骤

安装 Home Assistant: 如果还没有安装 Home Assistant，请先根据官方文档完成安装和配置 (Home Assistant Getting Started)。
获取 Long-Lived Access Token: 在 Home Assistant 中创建一个 Long-Lived Access Token，用于服务器API访问认证。

配置环境变量:

编辑 '.env' 文件，填入你的 Home Assistant Base URL 和 Long-Lived Access Token，例如：

HOMEASSISTANT_TOKEN=your_long_lived_access_token_here
HOMEASSISTANT_BASE_URL=http://your_home_assistant_ip:8123  # 请替换为你的 Home Assistant 地址

安装 Python 依赖: 确保你的 Python 环境中安装了必要的依赖包。虽然仓库中 'tcp_server_test.py' 文件头部有依赖声明，但更推荐使用 'uv sync' 命令同步依赖 (需要先安装 'uv' 包管理器，参考 README.md 构建和发布部分):
```
uv sync
```

服务器配置

MCP 服务器需要配置在 MCP 客户端中才能使用。以 Claude 客户端为例，你需要编辑 Claude 的配置文件 ('claude_desktop_config.json')，在 'mcpServers' 字段下添加如下配置：

"mcpServers": {
  "home-assistant-server": {  // 服务器名称，可以自定义
    "command": "uv",         // 启动命令，这里使用 uv 运行器
    "args": [                // 启动参数
      "--directory",        // 指定服务器代码目录
      "/path/to/home-assistant-server", // 请替换为你的 Home Assistant MCP Server 项目的绝对路径
      "run",                // uv 运行命令
      "src/home_assistant_mcp/server.py" // 服务器启动脚本路径，相对于项目根目录
    ]
  }
}

注意: 请将 '/path/to/home-assistant-server' 替换为你实际的 Home Assistant MCP Server 项目的绝对路径。

基本使用方法

启动 MCP 服务器: 配置完成后，Claude 客户端 (或其他 MCP 客户端) 应该能够自动启动 Home Assistant MCP Server。
在 LLM 客户端中使用: 在 Claude (或其他 LLM 客户端) 中，你可以使用自然语言指令来控制你的智能家居设备。例如，你可以对 Claude 说：
- "打开客厅的灯"
- "把卧室空调温度调到25度"
- "解锁大门"
- "关闭加湿器"
- "解除安防警报，密码是1234"
LLM 客户端会解析你的指令，并调用 Home Assistant MCP Server 提供的工具来执行相应的操作。

调试: 如果遇到问题，可以使用 MCP Inspector 工具进行调试，具体方法参考 README.md 的调试部分。

关键词