🚀 家庭助手 MCP 服务器
家庭助手 MCP 服务器是一个与 Home Assistant 集成的 Model Context Protocol (MCP) 服务器，借助它，LLM 能够对您的智能家居进行控制与查询，为智能家庭管理带来便捷。
🚀 快速开始
家庭助手 MCP 服务器可让您轻松利用自然语言与智能家居交互。以下为您介绍基本的使用流程：
- 完成服务器的安装与配置。
- 启动服务器。
- 选择合适的客户端（如Claude Desktop）与之集成，开启智能家庭控制之旅。
✨ 主要特性
- 自然语言交互：支持使用自然语言对家庭助手实体进行查询和控制，操作更加便捷。
- 广泛兼容：支持任何 MCP 兼容客户端，例如 Claude Desktop。
- 功能丰富：提供状态管理、服务调用、历史记录等实用工具。
- 安全可靠：采用家庭助手长期访问令牌进行安全身份验证，保障系统安全。
- 灵活传输：具备多种传输选项，标准 I/O 适用于本地进程，SSE 适用于远程客户端。
- 演示模式：在没有家庭助手的情况下，可使用模拟数据进行测试和演示。
📦 安装指南
您可以选择使用 bun 全局安装，或者从源代码进行安装：
# 使用 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 # 家庭助手实例的 URL
HASS_TOKEN=your_long_lived_access_token # 长期使用的访问令牌
# 可选配置
PORT=3000 # HTTP 服务器端口（默认：3000）
HASS_MOCK=false # 启用 mock 数据模式以在没有家庭助手时进行测试和演示（默认：false）
环境变量
| 变量 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|
HASS_URL |
是 | - | 家庭助手实例的 URL（例如，http://homeassistant.local:8123） |
HASS_TOKEN |
是 | - | 用于与家庭助手身份验证的长期访问令牌 |
PORT |
否 | 3000 | HTTP/SSE 运输使用的服务器端口数 |
HASS_MOCK |
否 | false | 设置为 "true" 时，启用 mock 数据模式以在没有家庭助手连接时进行测试 |
获取长期访问令牌的步骤如下：
- 登录到您的家庭助手实例。
- 点击底部左侧的个人资料。
- 滚动到底部“长寿命访问令牌”。
- 创建一个具有描述性名称的新令牌。
- 复制令牌值（您将不会再看到它）。
使用
作为独立服务器运行
# 标准模式（需要运行中的家庭助手实例）
home-assistant-mcp-server # 使用 HTTP/SSE 运输启动
home-assistant-mcp-server --stdio # 使用标准 I/O 启动
# 演示模式
npm start -- --mock
集成到 Claude Desktop
将 MCP 服务器配置为环境变量：
export MCP_SERVER_URL=http://localhost:5005
export MCP_SERVER_INSECURE=true
然后运行 Claude。
安全注意事项
- 避免在不安全的网络中暴露令牌。
- 考虑使用具有有限权限的令牌。
- 定期更新令牌以增强安全性。
📄 许可证
此项目在 MIT License 下许可 - 有关详细信息，请参阅 LICENSE 文件。