🚀 家庭助手 MCP 服务器

家庭助手 MCP 服务器是一个与 Home Assistant 集成的 Model Context Protocol (MCP) 服务器，它能让大语言模型（LLM）控制和查询您的智能家居系统，为智能家居的交互提供了更智能、便捷的方式。

🚀 快速开始

家庭助手 MCP 服务器可让您使用自然语言与智能家居交互，还支持多种客户端。以下是快速上手的步骤：

1. 完成服务器的安装。
2. 进行必要的配置。
3. 启动服务器并开始使用。

✨ 主要特性

• 自然语言交互：支持使用自然语言查询和控制家庭助手实体，让操作更加便捷。
• 广泛兼容性：支持任何 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 文件。