mcp-ha：一个 Home Assistant 附加组件，提供 MCP 服务器

这个 Home Assistant 附加组件暴露了一个 MCP（Model Context Protocol）服务器。实际上：你可以将 Claude、Gemini 或任何其他 MCP 客户端连接到你的实例，然后和你的家交谈。

“哪些灯还亮着？”、“为什么昨晚没有触发暖气的自动化？”、“把这一周的能源使用情况画成图给我看看。”

文档：devitek.github.io/mcp-ha（英文和法文）

覆盖内容

共 16 个工具，旨在节省 LLM 上下文窗口：压缩、分页和限制大小的响应，并有注释引导助手进行更精确的查询。

Related MCP server: hass-mcp

为什么不用官方 HA MCP 集成？

官方 HA MCP 集成确实存在并能正常工作，但它走的是 Assist API：只能访问已暴露给 Assist 的实体，没有历史记录、没有仓库、没有插件、没有自动化配置。这个附加组件提供直接、细粒度的访问。两者可以同时存在。

安装

要求：Home Assistant OS 或手工管理的（需要 Supervisor）。

1. 将这个仓库添加到你的附加组件存储库：

   

   或者手动：设置 ** 选项，其余 * 有三个，展开之后：Settings（加载项）> Add-on store（附加店）> 三个点菜单 > Repositories（仓库），然后粘贴 https://github.com/Devitek/mcp-ha。

2. 安装“MCP Home Assistant”并启动它。

3. 打开加载项的“配置”页：首次启动时会在那里显示一个 API 令牌（它也会打印在加载项的日志中）。

连接客户端

Claude Code：

claude mcp add --transport http home-assistant \
  http://HA_IP:9583/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop 和 Gemini CLI：请参考文档站上的客户端指南。

安全概述

• 默认只读。 内部被调用，服务调用工具对客户端根本不存在，除非你启用 allow_write。

• 纵深防御包括：危险服务白名单（HA 关机、dry_run 模式，shell_command...）、实体的 glob 允许/拒绝列表、dry_run 模式，以及记录每次尝试的 JSON 审计日志。

• 仅限局域网。 没有 TLS、没有 OAuth：不要将端口 9583 暴露到互联网。

完整的威胁模型见 SECURITY.md。

文档

• 文档站：安装、配置、客户端、工具参考、架构（英文和法文）

• 附加组件文档：HA 界面中显示的那个组件支持.NET

• 贡献指南：开发环境、代码归一化、发布

• 仓库 issues：知识库，每个设计决策和坑都通过 décision 和 écueil 标签（法语）进行跟踪。

许可证

MIT