Home Assistant Mcp Server

🚀 家庭助手 MCP 服务器

家庭助手 MCP 服务器是一个与 Home Assistant 集成的 Model Context Protocol (MCP) 服务器，借助它，LLM 能够对您的智能家居进行控制与查询，为智能家庭管理带来便捷。

🚀 快速开始

家庭助手 MCP 服务器可让您轻松利用自然语言与智能家居交互。以下为您介绍基本的使用流程：

1. 完成服务器的安装与配置。
2. 启动服务器。
3. 选择合适的客户端（如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）

环境变量

获取长期访问令牌的步骤如下：

1. 登录到您的家庭助手实例。
2. 点击底部左侧的个人资料。
3. 滚动到底部“长寿命访问令牌”。
4. 创建一个具有描述性名称的新令牌。
5. 复制令牌值（您将不会再看到它）。

使用

作为独立服务器运行

# 标准模式（需要运行中的家庭助手实例）
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 文件。