家庭助理 MCP 服务器

用于与Home Assistant集成的模型上下文协议 (MCP)服务器，允许 LLM 控制和查询您的智能家居。

特征

通过自然语言查询和控制 Home Assistant 实体
可与任何兼容 MCP 的客户端（如 Claude Desktop）配合使用
提供状态管理、服务调用、历史记录等工具
使用 Home Assistant 长期访问令牌进行安全身份验证
多种传输选项（本地进程的 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`	是的	-	用于通过 Home Assistant 进行身份验证的长期访问令牌
`PORT`	不	3000	使用 HTTP/SSE 传输时 HTTP 服务器的端口号
`HASS_MOCK`	不	错误的	设置为“true”时，启用模拟数据模式，以便在没有 Home Assistant 连接的情况下进行测试

要获取长期访问令牌：

登录您的 Home Assistant 实例
点击您的个人资料（左下角）
向下滚动到“长寿命访问令牌”
创建具有描述性名称的新令牌
复制令牌值（你不会再看到它）

用法

作为独立服务器运行

# 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 一起使用：

编辑您的 Claude Desktop 配置文件：
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows： %APPDATA%\Claude\claude_desktop_config.json
添加服务器配置：

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

如果您正在运行 Home Assistant，只需删除--mock标志并将HASS_MOCK设置为false 。

重启Claude桌面

可用工具

该服务器公开了几个与 Home Assistant 交互的工具：

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

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

安全

此服务器需要具有完全访问权限的 Home Assistant 访问令牌。请考虑以下安全建议：

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

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

Home Assistant MCP Server

Integrations

家庭助理 MCP 服务器

特征

安装

配置

环境变量

用法

作为独立服务器运行

与 Claude Desktop 集成

可用工具

安全

执照