使用说明

项目简介

该项目是一个 MCP (Model Context Protocol) 服务器，它将你的 Home Assistant 智能家居系统连接到支持 MCP 协议的 LLM (大型语言模型) 客户端。通过这个服务器，LLM 可以访问和控制你的 Home Assistant 设备，例如查询传感器数据、控制灯光、执行自动化场景等。

主要功能点

工具 (Tools) 桥接: 将 Home Assistant 的服务 (Services) 作为 MCP 工具暴露给 LLM，允许 LLM 调用 Home Assistant 的各种功能。
Prompt 模板 (Prompts) 桥接: 将 Home Assistant 中预定义的 Prompt 模板暴露给 LLM，支持在 LLM 交互中使用 Home Assistant 的上下文信息。
资源 (Resources) 管理 (待确认): 虽然代码中未明确提及资源管理，但 MCP 服务器通常具备资源管理能力。此项目可能通过工具和 Prompt 模板间接管理 Home Assistant 的实体 (Entities) 作为资源。
标准化接口: 使用 MCP 协议与 LLM 客户端通信，提供标准化的智能家居上下文访问方式。

安装步骤

安装 Home Assistant 自定义组件:
- 访问 home-assistant-model-context-protocol 并按照说明安装 Home Assistant 自定义组件。
- 这个组件是 Home Assistant 与 MCP 服务器通信的桥梁，必须先安装。
创建 Home Assistant Long Lived Access Token:
- 访问 Home Assistant 官方文档学习如何创建 Long Lived Access Token。
- MCP 服务器需要使用 Token 来安全地连接到你的 Home Assistant 实例。

克隆仓库到本地:

git clone https://github.com/allenporter/mcp-server-home-assistant.git
cd mcp-server-home-assistant

服务器配置 (以 Claude Desktop 为例)

以下是在 Claude Desktop 中配置该 MCP 服务器的示例 JSON 配置。你需要根据你的实际环境进行修改。

{
    "mcpServers": {
        "Home-assistant": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/mcp-server-home-assistant", // **请替换为你的 mcp-server-home-assistant 仓库的本地路径**
                "run",
                "mcp-server-home-assistant",
                "-v",
                "-v"
            ],
            "env": {
                "HOME_ASSISTANT_WEB_SOCKET_URL": "http://your-home-assistant-ip:8123/api/websocket", // **请替换为你的 Home Assistant WebSocket URL，例如 http://localhost:8123/api/websocket 或你的域名/ip:8123/api/websocket**
                "HOME_ASSISTANT_API_TOKEN": "YOUR_LONG_LIVED_ACCESS_TOKEN" // **请替换为你之前创建的 Home Assistant Long Lived Access Token**
            }
        }
    }
}

配置参数说明:

'"server name": "Home-assistant"': 服务器名称，可以自定义，用于在 MCP 客户端中标识该服务器。
'"command": "uv"': 运行服务器的命令。这里使用 'uv' 是一个高性能的 Python 包安装和运行工具，你可能需要先安装 'uv' ('pip install uv')。如果你的环境没有 'uv'，也可以尝试使用 'python' 或 'python3'，并相应地调整 'args' 中的模块路径。
'"args": [...]': 传递给 'command' 的参数列表：
- '"--directory", "/path/to/mcp-server-home-assistant"': 指定 MCP 服务器代码所在的目录。请务必替换为你的实际仓库路径。
- '"run", "mcp-server-home-assistant"': 使用 'uv run' 运行 'mcp_server_home_assistant' Python 模块 (对应 'mcp_server_home_assistant/main.py')。
- '"-v", "-v"': 可选参数，用于增加日志输出的详细程度，方便调试。
'"env": {...}': 环境变量配置：
- '"HOME_ASSISTANT_WEB_SOCKET_URL": "http://your-home-assistant-ip:8123/api/websocket"': 请替换为你的 Home Assistant WebSocket API 的完整 URL。 确保 URL 指向你的 Home Assistant 实例的 WebSocket 接口。
- '"HOME_ASSISTANT_API_TOKEN": "YOUR_LONG_LIVED_ACCESS_TOKEN"': 请替换为你之前在 Home Assistant 中创建的 Long Lived Access Token。

注意: 你需要将上述配置 JSON 内容添加到你的 MCP 客户端 (例如 Claude Desktop) 的配置文件中。具体的配置文件位置和修改方法请参考你使用的 MCP 客户端的文档。

基本使用方法

确保 Home Assistant 实例正在运行，并且 'home-assistant-model-context-protocol' 自定义组件已正确安装。
启动 MCP 服务器：根据 MCP 客户端的配置，客户端会自动启动该 MCP 服务器。你也可以在本地环境中手动运行服务器，例如在仓库目录下执行命令 'uv run mcp-server-home-assistant --url "你的WebSocket URL" --token "你的Token" -v -v' (替换 URL 和 Token 为你的实际信息)。
在支持 MCP 协议的 LLM 客户端中，配置并连接到该 "Home-assistant" 服务器。
现在，LLM 应该可以通过 MCP 协议访问 Home Assistant 的工具和 Prompt 模板，从而实现智能家居控制和信息查询等功能。你可以尝试在 LLM 中使用自然语言指令来与你的 Home Assistant 设备进行交互。

查看日志

可以通过查看日志文件 '~Library/Logs/Claude/mcp-server-Home-assistant.log' (Claude Desktop 默认日志路径) 来了解服务器的运行状态和错误信息。

关键词