Ambient Home Assistant MCP

Ambient Home Assistant MCP 是一个安全、语义化的桥梁，为 ChatGPT 和其他 MCP 客户端提供对 Home Assistant 的专用访问。它是未来面向用户的 Ambient Home Assistant 应用的服务器基础。

第二阶段状态： 本地/私有且只读。此版本增加了语义实体发现、当前状态、区域、楼层和域摘要。它无法控制设备或更改 Home Assistant。

它是什么——以及它不是什么

该桥梁是一个抽象和安全层。随着时间的推移，它可以在 Home Assistant REST、WebSocket 和原生 MCP/Assist 接口之间进行选择，同时向模型呈现小型语义工具。

它不是：

• 不是 Home Assistant 的替代品；

• 不是不受限制的 Home Assistant 管理员 API；

• 不是暴露给 LLM 的通用 API 包装器；或

• 不是 Home Assistant 的 /api/mcp 端点的反向代理。

Related MCP server: ha-ai-learner

架构

flowchart TD
    C[ChatGPT or MCP client] -->|MCP| A[Ambient Home Assistant MCP]
    A --> T[Semantic tools]
    A --> P[Policy and security]
    A --> N[Normalized data and diagnostics]
    T --> H[Home Assistant client facade]
    P --> H
    N --> H
    H --> R[REST state API]
    H --> W[WebSocket registries]
    H -. selective future use .-> M[HA MCP or Assist API]

MCP 工具从不发出原始 HTTP 请求。它们依赖于 HomeAssistantClient，该客户端负责接口选择并立即规范化上游响应。请参阅架构决策记录。

能力

未实现任何服务调用、状态更改或管理端点。

安全模型

• Home Assistant 令牌仅来自运行时配置，并使用 Pydantic 秘密类型。

• 日志是结构化的，并编辑掉承载令牌和常见凭据字段。

• 原始 /api/config 数据在到达工具结果之前被缩减为允许列表模型。

• 详细的实体属性使用显式允许列表，并排除 URL、摄像头源、令牌、凭据、坐标和包含位置信息的元数据。

• 当前状态从不缓存。注册表元数据使用一个有界的 60 秒 TTL 缓存，以避免重复的 WebSocket 认证和注册表读取。

• MCP 传输主机和来源允许列表可防止 DNS 重绑定。

• 策略引擎允许读取，并对每个控制类失败关闭。

• 容器在 Compose 中以非 root 用户身份运行，并使用只读文件系统。

切勿提交 .env、Home Assistant 令牌、凭据、私有 URL 或证书。在进行任何部署工作之前，请参阅安全。

快速开始

要求：Python 3.12+ 和 uv。

cp .env.example .env
# Edit .env and provide HOME_ASSISTANT_URL and HOME_ASSISTANT_TOKEN.
uv sync --all-extras
uv run ambient-ha-mcp

Streamable HTTP MCP 端点为 http://127.0.0.1:8000/mcp；健康检查位于 http://127.0.0.1:8000/health。

在本地检查工具：

npx @modelcontextprotocol/inspector@latest

然后将 Inspector 连接到 http://127.0.0.1:8000/mcp。

开发命令

uv sync --all-extras          # install
uv run ambient-ha-mcp         # run locally
uv run pytest                 # unit tests; real HA tests skip by default
uv run ruff check .           # lint
uv run ruff format --check .  # formatting check
uv run mypy                   # type check
docker build -t ambient-ha-mcp .
docker compose up --build

在有意更改依赖项后重新生成依赖锁：

uv lock

Docker Compose

将 .env.example 复制为 .env，提供两个必需的 Home Assistant 设置，然后运行 docker compose up --build。Compose 仅发布到主机回环地址。

Docker 健康探针测试应用程序存活状态。临时 Home Assistant 中断会将 /health 更改为 status: degraded，但保持 HTTP 状态 200，以便编排器不会循环重启健康的桥梁。

文档

• 架构

• 安全

• 工具契约

• 开发

• ChatGPT 设置和当前限制

许可证

MIT。请参阅 LICENSE。