Hass-MCP

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

概述

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

• 查询设备和传感器的状态

• 控制灯、开关和其他实体

• 获取智能家居的摘要

• 自动化和实体故障排除

• 搜索特定实体

• 为常见任务创建引导式对话

Related MCP server: MCP Python Toolbox

截图

特征

• 实体管理：获取状态、控制设备和搜索实体

• 领域摘要：获取有关实体类型的高级信息

• 自动化支持：列出并控制自动化

• 引导式对话：使用提示执行常见任务，例如创建自动化

• 智能搜索：按名称、类型或状态查找实体

• 令牌效率：精简 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 许可证