Home Assistant MCP

一个受 OAuth 保护的 模型上下文协议 (MCP) 服务器， 用于安全地将 ChatGPT、Codex 及其他 MCP 客户端连接到 Home Assistant。

该项目公开了 99 个类型化工具，用于发现、仪表板、日程、气候、能源、媒体、清洁、灌溉、自动化、诊断以及经过仔细约束的设备控制。它保持 Home Assistant 的 API 私有，并刻意避免成为通用 shell、日志读取器、网络扫描器或不受限制的服务代理。

[!重要] 这是一个针对自托管 Home Assistant 安装的安全敏感参考实现。阅读 安全模型，替换每个示例值，并在连接到真实家庭之前审查允许列表。

亮点

• 类型化的 Home Assistant 访问： 实体、设备、区域、历史、天气、 日历、日程、统计、集成、仪表板、待办列表、 自动化、备份和系统健康。

• 受限写入： 气候、灯光、场景、媒体播放器、吸尘器、窗帘、 锁、警报器、通知、仪表板、日程、日历、待办事项 和自动化使用经过验证的输入和狭窄的服务允许列表。

• 洒水器支持： 实时控制器状态、区域元数据、配置、 浇水历史、遥测刷新、区域或序列启动，以及幂等 停止操作。

• 能源和 SolarEdge： 发电量、模块比较、功率流、能源 细分、存储摘要、遥测、警报，以及可选的 Home Assistant 桥接集成。

• 持久能力同步： 每五分钟将 Home Assistant 当前的服务 注册表与已审查的发布基线进行比较，并报告 漂移，而不会动态暴露新的写入。

• 消毒诊断： 可选的固定路由、主机/运行时、中断和 固定子网 LAN 证据，具有严格限制，不包含原始地址、任意 目标、命令或设备控制。

• OAuth 原生远程访问： 授权码流程，使用 S256 PKCE、 动态客户端注册、作用域访问令牌和 MCP 资源元数据。

版本 2.6.1 当前宣传 99 个工具。参见 CHANGELOG.md 了解发布历史。

架构

flowchart LR
    Client[ChatGPT, Codex, or MCP client]
    Edge[HTTPS edge<br/>Cloudflare Worker, tunnel, or reverse proxy]
    MCP[Home Assistant MCP<br/>OAuth + typed tools]
    HA[Private Home Assistant API]
    Data[(OAuth, audit, and<br/>capability-sync state)]
    Collector[Optional root-owned<br/>diagnostics collector]
    Export[Sanitized read-only export]

    Client -->|HTTPS + OAuth/PKCE| Edge
    Edge -->|loopback or shared-secret origin| MCP
    MCP -->|long-lived service token| HA
    MCP --> Data
    Collector --> Export --> MCP

参考部署将 MCP 服务绑定到 127.0.0.1:8000。只有 HTTPS 边缘是公开的。Home Assistant 可以保持本地主机或通过 私有网络可达。

工具表面

较高风险的操作被注释为破坏性的，并要求显式 确认参数。确切的注册表是权威的；部署后从经过身份验证的 MCP 客户端检查它。

要求

• Home Assistant 可从 MCP 主机访问。

• 专用的 Home Assistant 长期访问令牌。尽可能使用单独的服务 身份。

• Python 3.12 或更高版本，以及 uv 用于开发和 测试。

• 用于参考容器部署的 Docker 和 Compose。

• 用于远程 MCP 客户端的公共 HTTPS URL。

• 一个 HTTPS 边缘，通过回环访问 MCP 或注入配置的 来源共享密钥。附带的 Caddy 和 Cloudflare 示例演示了 这两种模式。

• 仅当使用可选的主机诊断收集器时，才需要 Linux 和 systemd。

捆绑的 Compose 文件是生产参考，不是通用的单命令 安装程序。它假定主机网络、现有的 Home Assistant 配置 位于 /opt/homeassistant/config，以及已安装的诊断导出 位于 /var/lib/ha-host-diagnostics/export。调整这些挂载以适应您的安装， 而不要暴露 Home Assistant API 或 Docker 套接字。

开发快速入门

克隆仓库并安装锁定的依赖项：

git clone https://github.com/shogun301/ha-chatgpt-mcp.git
cd ha-chatgpt-mcp
uv sync --frozen

测试套件和公共源审计不需要生产凭据：

uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

要运行服务，请将 .env.example 复制到被忽略的 .env，替换每个 示例域和实体 ID，并提供下面描述的所需运行时路径和秘密 文件。应用程序不会自动加载 .env； 在您的进程管理器中导出变量，使用 uvicorn --env-file .env，或 让 Docker Compose 加载它。

对于配置环境后的本地进程：

uv run uvicorn app.server:app --host 127.0.0.1 --port 8000 --no-proxy-headers

对于调整其挂载和可选 集成后的参考容器部署：

docker compose build --pull
docker compose up -d
curl --fail http://127.0.0.1:8000/healthz

不要将 Uvicorn 直接绑定到公共接口。

配置

核心设置

.env.example 中的实体特定变量将通用工具表面映射到一个 部署的存在、通知、吸尘器、洒水器、恒温器和日程 实体。将真实实体 ID 保留在本地配置中，而不是 Git 中。

必需的秘密文件

服务器从文件而不是环境值读取秘密：

使用加密安全生成器生成随机值。可以生成 Argon2 密码哈希，而无需将密码放入 shell 历史记录：

uv run python -c "from argon2 import PasswordHasher; from getpass import getpass; print(PasswordHasher().hash(getpass('OAuth password: ')))"
uv run python -c "import secrets; print(secrets.token_urlsafe(48))"

将输出存储在具有仅所有者权限的单独文件中。切勿提交 secrets/、.env、令牌、密码、哈希、私有域、实体 清单、日程或网络拓扑。

可选的 SolarEdge 配置

SolarEdge 支持使用可选的客户端凭据、加密令牌存储、 桥接秘密、重定向 URI 和受保护的门户回退凭据。如果您 不使用 SolarEdge，请省略相应的 SOLAREDGE_*_FILE 变量。参考 Compose 文件设置这些路径，因此要么提供文件，要么在本地覆盖中删除这些条目。

OAuth 作用域

• mcp:read 允许读取工具。

• mcp:write 允许已审查的写入表面，并且还满足当前 最强的兼容性授权。

• mcp:diagnostics 与 mcp:read 一起，允许特权只读主机 和 LAN 诊断，而不会授予设备写入。

将客户端连接到 https://your-mcp-host.example/mcp。服务器发布 OAuth 授权服务器、受保护资源、OpenID 配置和 动态客户端注册元数据，位于同一来源下。

边缘选项

应用程序要求非回环请求携带配置的 来源共享密钥。包含两个示例：

• cloudflare/ 包含一个狭窄的 Cloudflare Worker 代理。它 仅转发 MCP、OAuth、健康检查和 SolarEdge 回调路径，强制执行 1 MiB 请求限制，添加来源秘密，并剥离不必要的标头。

• Caddyfile 提供同主机 HTTPS 反向代理到 回环 MCP 监听器。

附带的 cloudflared 服务使用令牌文件，并且仅在回环上发布指标。 替换所有示例路由，并保持 MCP 来源、Home Assistant API 和指标监听器远离公共网络。

能力同步

Home Assistant 集成可以独立于此项目添加或删除服务。 因此，服务器每五分钟轮询 Home Assistant 的服务注册表， 并在 /data/ha-capability-sync.json 中持久化发布绑定的基线。

get_capability_sync_status 报告添加或删除的服务以及字段模式 跨重启的变化。监视器刻意是观察性的：它从不调用 服务，也从不将未经审查的 Home Assistant 服务变成新的 MCP 写入工具。新功能应通过 Git 审查、实现为类型化工具、测试并发布。

可选的主机和 LAN 诊断

collector/ 下的 systemd 收集器没有监听器，并且 不接受调用者选择的命令、路径、容器、日志表达式或 URL。它 将受限的、消毒的快照和账本发布到固定目录。MCP 容器仅接收该目录作为只读挂载——绝不接收 Docker 套接字、主机日志、procfs、sysfs 或 systemd 控制。

LAN 工具仅在配置的 /24 内操作，返回不透明的节点 ID， 使用封闭的 TCP 服务允许列表，不发送应用程序负载，并省略原始 地址。它们无法扫描任意网络或控制设备。

参见 docs/operations.md 和 collector/README.md 了解完整的数据模型、保留 限制、部署、验证、事件和回滚程序。

安全模型

此服务器有意比 Home Assistant API 的范围更窄：

• 不支持 shell 执行、任意 WebSocket 透传、任意文件、原始日志、Docker 管理、服务重启、关机、凭据检索、摄像头图像或警报解除。

• 通用 Home Assistant 服务调用按域和服务进行白名单限制；优先使用专用的类型化工具。

• 输入经过模式验证，结果大小受限，敏感诊断字段会被递归脱敏。

• 破坏性或物理操作使用显式注释和确认门控。

• 审计记录包含工具名称和受限元数据，不包含凭据或返回的诊断证据。

• 容器以非特权用户身份运行，文件系统只读，所有 Linux 能力被丢弃，并启用 no-new-privileges。

• 公开发布前的审计会同时扫描当前代码树和 Git 历史。

切勿将恒温器、灯光、门锁、吸尘器、洒水器、摄像头、扬声器、电视、备份、通知或其他物理副作用用作连通性测试。

有关漏洞报告和敏感部署信息的处理，请阅读 SECURITY.md。

部署与验证

scripts/deploy-production.ps1 中的 PowerShell 部署脚本是一个有主见的 AWS Lightsail 参考实现。它需要显式的 AWS 配置文件、区域、实例、前端 URL 和 MCP URL 参数；打包已审查的源代码；创建备份；部署收集器和容器；运行验证；并支持回滚。在将其适配到其他主机之前，请仔细审查。

在每次公开推送或生产发布之前：

uv sync --frozen
uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

然后在不改变设备状态的情况下进行验证：

1. /healthz 在本地和通过公共边缘均成功。

2. 未认证和无效令牌的 MCP 请求被拒绝。

3. 认证后的发现报告预期的版本和工具数量。

4. 只读概览、能力同步、路由和集成检查均成功。

5. 公共 Git 提交、部署的工件和报告的服务版本完全一致。

生产流程和回滚门控详见 docs/operations.md。

贡献

欢迎提交 issue 和 pull request，前提是保持项目有界的安全模型。

对于新工具：

1. 优先选择窄类型操作，而非通用透传。

2. 准确标注只读、幂等、写入或破坏性操作。

3. 验证实体域、枚举、长度、时间窗口和结果限制。

4. 对具有重大物理或管理后果的操作要求显式确认。

5. 添加授权、负面路径、脱敏和回归测试。

6. 更新能力文档并运行公开历史审计。

请勿在 issue、测试夹具、截图、提交或 pull request 中包含真实家庭配置、私有 URL、凭据、日志、令牌、日程、拓扑或提供商响应。

许可证

目前未包含开源许可证。公开可见性不授予复制、修改或重新分发代码的权限。仓库所有者应在接受重用或再分发之前添加明确的许可证。

参考

• Model Context Protocol

• OpenAI: Build an MCP server

• OpenAI: Authenticate users

• Cloudflare Tunnel monitoring

• Cloudflare Tunnel metrics