Home Assistant MCP 服务器

一个 Model Context Protocol (MCP) 服务器，用于与 Home Assistant 集成，允许 LLM（大语言模型）控制和查询您的智能家居。

功能

• 通过自然语言查询和控制 Home Assistant 实体
• 与任何 MCP 兼容的客户端（如 Claude Desktop）配合使用
• 提供状态管理、服务调用、历史记录等工具
• 使用 Home Assistant 的长期访问令牌进行安全认证
• 多种传输选项（本地进程使用 stdio，远程客户端使用 SSE）
• 当 Home Assistant 不可用时，提供带有模拟数据的演示模式以进行测试和演示

安装

bash

使用 bun 全局安装

bun install -g home-assistant-mcp-server

或者从源代码安装

git clone https://github.com/oleander/home-assistant-mcp-server.git cd home-assistant-mcp-server bun install bun run build bun link

配置

在当前目录下创建一个 .env 文件，并添加以下变量：

必要配置

HASS_URL=http://your-home-assistant:8123 # 您的 Home Assistant 实例的 URL HASS_TOKEN=your_long_lived_access_token # 用于认证的长期访问令牌

可选配置

PORT=3000 # HTTP 服务器端口号（默认：3000） HASS_MOCK=false # 当 Home Assistant 不可用时启用模拟数据模式（默认：false）

环境变量

获取长期访问令牌的方法：

1. 登录到您的 Home Assistant 实例
2. 点击您的个人资料（左下角）
3. 向下滚动到“长期访问令牌”
4. 创建一个具有描述性名称的新令牌
5. 复制令牌值（您将不会再看到它）

使用方法

作为独立服务器运行

bash

标准模式（需要运行中的 Home Assistant 实例）

home-assistant-mcp-server # 使用 HTTP/SSE 传输启动 home-assistant-mcp-server --stdio # 使用 stdio 传输启动，直接进程通信

演示模式（当 Home Assistant 不可用时使用模拟数据）

home-assistant-mcp-server --mock # 使用 HTTP/SSE 传输和模拟数据启动 home-assistant-mcp-server --stdio --mock # 使用 stdio 传输和模拟数据启动

与 Claude Desktop 集成

要与 Claude Desktop 一起使用：

1. 编辑您的 Claude Desktop 配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%Claudeclaude_desktop_config.json

2. 添加服务器配置：

json { "mcpServers": { "homeassistant": { "command": "home-assistant-mcp-server", "env": { "HASS_URL": "http://your-home-assistant:8123", "HASS_TOKEN": "your_token_here", "HASS_MOCK": "true" } } } }

如果您有正在运行的 Home Assistant，只需移除 --mock 标志并将 HASS_MOCK 设置为 false。

3. 重启 Claude Desktop

可用工具

服务器提供了几个用于与 Home Assistant 交互的工具：

• states - 查询实体状态
• lights - 列出灯光
• light - 控制灯光
• service - 调用 Home Assistant 服务
• history - 获取历史实体数据- services - 列出可用的服务
• config - 获取 Home Assistant 配置
• domains - 列出可用的域
• error_log - 获取 Home Assistant 错误日志
• devices - 获取 Home Assistant 中的所有设备

有关详细的使用示例，请参阅 docs/hass-mcp.md。

安全性

此服务器需要一个具有完全访问权限的 Home Assistant 访问令牌。请考虑以下安全建议：

• 仅在受信任的网络上运行服务器
• 如果远程暴露服务器，请使用 HTTPS
• 确保 .env 文件的安全，不要将其提交到源代码控制中
• 在可能的情况下，考虑使用权限有限的令牌

许可证

本项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。

来源

• 来源：github
• 链接：https://github.com/oleander/home-assistant-mcp-server