AI导哈

智能家居控制服务器

一个用于与Home Assistant集成的模型上下文协议（MCP）服务器，允许LLMs控制和查询智能家居。

  • by oleander
  • TypeScript
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 oleander/home-assistant-mcp-server

使用说明

家庭助理MCP服务器

A. 模型上下文协议（MCP） 用于集成的服务器 家庭助手，允许LLM控制和查询您的智能家居。

特性

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

安装

# Install globally using bun
bun install -g home-assistant-mcp-server

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

配置

创建一个 .env 当前目录中的文件，包含以下变量：

# Required configurations
HASS_URL=http://your-home-assistant:8123  # URL to your Home Assistant instance
HASS_TOKEN=your_long_lived_access_token   # Long-lived access token for authentication

# Optional configurations
PORT=3000                # Port for the HTTP server (default: 3000)
HASS_MOCK=false          # Enable mock data mode when Home Assistant is unavailable (default: false)

环境变量

变量 必填 默认 描述
HASS_URL 是 - Home Assistant实例的URL（例如。，http://homeassistant.local:8123)
HASS_TOKEN 是 - 用于与家庭助理进行身份验证的长期访问令牌
PORT 否 3000 使用HTTP/SSE传输时HTTP服务器的端口号
HASS_MOCK 否 false 设置为“true”时，启用模拟数据模式进行测试，而无需家庭助理连接

要获得长期访问令牌，请执行以下操作：

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

用法

作为独立服务器运行

# Standard mode (requires a running Home Assistant instance)
home-assistant-mcp-server                # Start with HTTP/SSE transport
home-assistant-mcp-server --stdio        # Start with stdio transport for direct process communication

# Demo mode (with mock data when Home Assistant is unavailable)
home-assistant-mcp-server --mock         # Start with HTTP/SSE transport and mock data
home-assistant-mcp-server --stdio --mock # Start with stdio transport and mock data

与Claude Desktop集成

要与Claude Desktop一起使用：

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

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • 窗户： %APPDATA%\Claude\claude_desktop_config.json

  2. 添加服务器配置：

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

如果您正在运行家庭助理，只需删除 --mock 标志和设置 HASS_MOCK 向 false.

  1. 重新启动克劳德桌面

可用工具

服务器提供了几个与家庭助理交互的工具：

  • states -查询实体状态
  • lights -列表灯
  • light -控制灯光
  • service -呼叫总部助理服务
  • history -检索历史实体数据
  • services -列出可用服务
  • config -获取家庭助理配置
  • domains -列出可用域
  • error_log -获取家庭助理错误日志
  • devices -获取家庭助理中的所有设备

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

安全

此服务器需要具有完全访问权限的家庭助理访问令牌。考虑以下安全建议：

  • 仅在受信任的网络上运行服务器
  • 如果远程暴露服务器，请使用HTTPS
  • 保持你的 .env 文件安全，不要将其提交给源代码管理
  • 尽可能考虑使用权限有限的令牌

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP