JinDaGe - home-assistant-mcp-server MCP Details

article

README

🚀 家庭助手 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 文件。

home-assistant-mcp-server