Hass-MCP

用于 Home Assistant 与 Claude 和其他 LLM 集成的模型上下文协议 (MCP) 服务器。

概述

Hass-MCP 使 Claude 等 AI 助手能够直接与您的 Home Assistant 实例进行交互，从而使他们能够：

• 查询设备和传感器的状态
• 控制灯、开关和其他实体
• 获取智能家居的摘要
• 自动化和实体故障排除
• 搜索特定实体
• 为常见任务创建引导式对话

截图

特征

• 实体管理：获取状态、控制设备和搜索实体
• 领域摘要：获取有关实体类型的高级信息
• 自动化支持：列出并控制自动化
• 引导式对话：使用提示执行常见任务，例如创建自动化
• 智能搜索：按名称、类型或状态查找实体
• 令牌效率：精简 JSON 响应以最大限度地减少令牌使用

安装

先决条件

• 具有长效访问令牌的 Home Assistant 实例
• 以下之一：
  • Docker（推荐）
  • Python 3.13+ 和uv

使用 Claude Desktop 进行设置

Docker 安装（推荐）

1. 拉取 Docker 镜像：
   docker pull voska/hass-mcp:latest
2. 将 MCP 服务器添加到 Claude Desktop：a. 打开 Claude Desktop 并转到“设置” b. 导航至“开发人员”>“编辑配置” c. 将以下配置添加到您的claude_desktop_config.json文件：
   { "mcpServers": { "hass-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "HA_URL", "-e", "HA_TOKEN", "voska/hass-mcp" ], "env": { "HA_URL": "http://homeassistant.local:8123", "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN" } } } }
   d. 将YOUR_LONG_LIVED_TOKEN替换为您的实际 Home Assistant 长期访问令牌 e. 更新HA_URL ：
   • 如果在同一台机器上运行 Home Assistant：使用http://host.docker.internal:8123 （Mac/Windows 上的 Docker Desktop）
   • 如果在另一台机器上运行 Home Assistant：使用实际的 IP 或主机名

   f.保存文件并重新启动Claude Desktop

3. “Hass-MCP”工具现在应该出现在您的 Claude Desktop 工具菜单中

注意：如果您在同一台机器上的 Docker 中运行 Home Assistant，则可能需要在 Docker 参数中添加--network host ，以便容器能够访问 Home Assistant。或者，使用您机器的 IP 地址，而不是host.docker.internal 。

其他 MCP 客户端

光标

1. 前往“光标设置”>“MCP”>“添加新的 MCP 服务器”
2. 填写表格：
   • 名称： Hass-MCP
   • 类型： command
   • 命令：
     docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
   • 将YOUR_LONG_LIVED_TOKEN替换为你的实际 Home Assistant 令牌
   • 更新 HA_URL 以匹配您的 Home Assistant 实例地址
3. 点击“添加”保存

克劳德代码（CLI）

要与 Claude Code CLI 一起使用，您可以使用mcp add命令直接添加 MCP 服务器：

使用 Docker（推荐）：

将YOUR_LONG_LIVED_TOKEN替换为您的实际 Home Assistant 令牌，并更新 HA_URL 以匹配您的 Home Assistant 实例地址。

使用示例

设置好 Hass-MCP 后，您可以与 Claude 一起使用以下提示的一些示例：

• “我客厅的灯现在怎么样？”
• “把厨房里的灯都关掉”
• “列出所有包含温度数据的传感器”
• “给我一份我的气候实体的摘要”
• “创建一个在日落时打开灯的自动化装置”
• “帮我解决卧室运动传感器自动化系统无法工作的问题”
• “搜索与我的客厅相关的实体”

可用工具

Hass-MCP 提供了几种与 Home Assistant 交互的工具：

• get_version ：获取 Home Assistant 版本
• get_entity ：使用可选字段过滤获取特定实体的状态
• entity_action ：对实体执行操作（打开、关闭、切换）
• list_entities ：获取具有可选域过滤和搜索的实体列表
• search_entities_tool ：搜索与查询匹配的实体
• domain_summary_tool ：获取域实体的摘要
• list_automations ：获取所有自动化的列表
• call_service_tool ：调用任何 Home Assistant 服务
• restart_ha ：重启 Home Assistant
• get_history ：获取实体的状态历史记录
• get_error_log ：获取 Home Assistant 错误日志

引导式对话提示

Hass-MCP 包含几个引导对话的提示：

• create_automation ：基于触发器类型创建 Home Assistant 自动化的指南
• debug_automation ：针对无法正常工作的自动化的故障排除帮助
• troubleshoot_entity ：诊断实体问题
• routine_optimizer ：分析使用模式并根据实际行为建议优化例程
• automation_health_check ：审查所有自动化，发现冲突、冗余或改进机会
• entity_naming_consistency ：审核实体名称并提出标准化改进建议
• dashboard_layout_generator ：根据用户偏好和使用模式创建优化的仪表板

可用资源

Hass-MCP 提供以下资源端点：

• hass://entities/{entity_id} ：获取特定实体的状态
• hass://entities/{entity_id}/detailed ：获取有关实体的所有属性的详细信息
• hass://entities ：列出按域分组的所有 Home Assistant 实体
• hass://entities/domain/{domain} ：获取特定域的实体列表
• hass://search/{query}/{limit} ：搜索与自定义结果限制匹配的查询的实体

发展

运行测试

执照

MIT 许可证