Hive heating

---

重要

hive-mcp 是一个非官方项目，并非由 Hive、British Gas 或 Centrica 制作、认可或提供支持。Hive 没有公开 API：hive-mcp 使用与 Hive 应用和 Home Assistant 集成相同的未公开 API，Hive 可随时更改该 API。

“这里冷死了。能把家里暖和起来吗？” 客厅温度为 17.5 °C，供暖正按计划运行，计划要求在 17:00 前保持 16 °C。我可以将温度提升到 21 °C，持续一小时，之后恢复按计划运行。需要这样做吗？ “好，再把热水也打开，我想洗个澡。” 好了：供暖将提升到 21 °C，持续到 15:40；热水将提升 30 分钟。顺便说一句，卧室散热器阀门的电池电量只剩 20% 了。

用日常语言询问家中情况。助手会从 24 个工具中选择合适的工具来查询信息；如果您允许，也可以进行更改。以下是一些示例：

• 🌡️ “每个房间有多暖和？供暖开着吗？”
• 🔥 “把供暖温度提升到 21 度，持续一小时。”
• 🛁 “我想半小时后洗澡。热水开着吗？”
• 🧳 “我们从周六开始外出，到 28 号回来。设置假期模式。”
• 🔋 “我的 Hive 设备有没有需要更换电池的？”
• 💡 “把客厅灯光调到 30%，并关闭台灯插座。”

亮点

• 🐳 Docker 优先，体积小巧。 一个镜像（ghcr.io/mattoddie/hive-mcp），支持 linux/amd64 和 linux/arm64，大小约为 20 MB。它是在 distroless 基础镜像上运行的单个静态 Go 二进制文件，不含 shell 或包管理器，并以非 root 用户运行。它可通过 Streamable HTTP 提供长时间运行的服务，也可通过 stdio 运行 docker run -i。你也可以单独运行该二进制文件。对于 Claude Desktop，还有一个一键安装扩展包（.mcpb），无需 Docker。
• 🛡️ 默认安全。 除非启用写入功能，否则服务只读。未获允许的工具根本不会注册，每项更改也都会先经过检查：供暖温度目标必须在 5–25 °C 之间，且以 0.5 为步进（通过 HIVE_MAX_TEMP 提高上限）；增强模式最长为六小时，假期模式最长为 60 天；对于持续时间不受限的设置（手动供暖、开启热水），则需要明确确认。
• 📱 一次输入短信验证码。 Hive 登录需要输入通过短信发送的验证码。你只需通过 hive-mcp login 输入一次，服务便会将自身注册为已记住的设备，之后无需再次输入验证码即可自行登录。密码、令牌和设备密钥绝不会出现在工具输出或日志中。
• 🔐 真正的 Cognito SRP。 它以 Hive 应用相同的方式登录（使用 AWS Cognito 和 SRP，不会发送你的密码），并通过 Home Assistant 客户端使用的精确数学计算进行验证。
• 🐢 减轻 Hive 负担。 读数会缓存 30 秒，避免对话频繁调用 Hive 并未打算供我们使用的 API；遇到速率限制或登录失败时，它也会降低请求频率。
• 🎛️ 可调节。 只公开你需要的工具集，让模型上下文保持精简、专注。
• 🧪 经过测试。 测试套件针对模拟 Hive 运行，其中包含一个模拟 Cognito，可实际验证 SRP 证明、短信验证码和已记住的设备。

快速开始

使用 Claude Desktop？ 无需 Docker：从最新版本下载适用于你电脑的扩展包（.mcpb），打开它进行安装，填写 Hive 邮箱和密码，然后让 Claude “登录 Hive”。请参阅 Claude Desktop。

hive-mcp 已列入 MCP Registry，名称为 io.github.mattoddie/hive-mcp，因此可浏览注册表的客户端可以安装它（stdio 模式下的 Docker 镜像，或扩展包）。请参阅从 MCP Registry 安装。

否则，你需要 Docker、一个可在 Hive 应用中正常使用的 Hive 账户、一部能接收 Hive 短信的手机，以及一个 MCP 客户端，例如 Claude Code。

1. 设置服务。

mkdir hive-mcp && cd hive-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/hive-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/hive-mcp/main/example.env -o .env
# Edit .env: set HIVE_USERNAME and HIVE_PASSWORD (your Hive app login)
# and a random MCP_AUTH_TOKEN (e.g. `openssl rand -hex 32`)

2. 登录 Hive 一次并启动服务。

docker compose run --rm hive-mcp login   # type in the code Hive texts you
docker compose up -d

3. 连接你的助手。

claude mcp add --transport http hive http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

现在，在 Claude Code 中询问*“家里有多暖？”*。

使用 Claude Desktop、VS Code、Cursor 或 Codex？请参阅连接 MCP 客户端。不想运行服务？使用 docker run -i 或本地二进制文件运行 stdio 模式。

启用更改

默认情况下，助手可以查看，但不能操作。若要让它更改供暖、热水、插座和灯，请将以下内容添加到 .env 并重启：

HIVE_ALLOW_WRITES=true
HIVE_TOOLSETS=home,heating,hotwater   # optional: expose fewer tools

docker compose up -d

启用写入前，请阅读安全。供暖系统是现实家庭中的真实设备。若要记录助手所做的每项更改，请将 HIVE_AUDIT_LOG 设置为文件路径（请参阅审计日志）。

功能

工具集	涵盖内容
home	登录、一键查看家庭概况、包含电池电量和信号强度的 Hive 设备列表，以及假期模式
heating	供暖区域和散热器阀门（TRV）区域：温度、模式和计划；设置温度或模式、启动和取消强力加热
hotwater	热水：状态和计划；开启、关闭或恢复计划，启动和取消强力加热
devices	智能插座、灯和传感器：开启或关闭、耗电量、亮度、色温、打开或关闭
raw	可调用 Hive API 任意路径的备用工具。默认关闭，需在列表中启用（HIVE_TOOLSETS=all,raw）

如需查看所有工具和参数，请参阅**工具参考**。现成的提示词（如 home_check、warm_up 和 going_away）会串联工具，完成常见任务。目前尚不支持更改计划；请参阅兼容性。

文档

文档也发布在 hive-mcp.mattoddie.dev/docs，并支持搜索。

🚀 快速入门	分步设置指南，包括一次性短信登录
🔌 连接 MCP 客户端	Claude Code、Claude Desktop、VS Code、Cursor、Codex、stdio 模式
⚙️ 配置	所有环境变量、登录和已记住设备的工作方式、Docker 密钥、工具集
🐳 部署	Compose、镜像标签、升级、TLS 反向代理、加固、无 Docker 运行
💬 使用 hive-mcp	对话示例、提示词、更改和强力加热的工作方式
🧰 工具参考	所有工具和提示词，由代码生成
🛡️ 安全	威胁模型、令牌文件包含的内容、安全写入设置
📡 兼容性	支持的 Hive 设备、已停产产品，以及非官方 API 的使用方式
🩹 故障排除	登录和短信问题、常见错误及修复方法
🛠️ 开发	架构、模拟 Hive、添加工具、测试

贡献

欢迎各种形式的贡献，包括错误报告、Hive API 行为说明、文档或新工具。请阅读贡献指南以开始参与，并遵守行为准则。如需报告漏洞，请参阅安全政策。请勿为此公开创建 issue。

许可证

MIT © Matt Oddie

hive-mcp 是一个独立的社区项目，与 Hive、British Gas 或 Centrica plc 无关联，也未获其认可或赞助。“Hive”和“British Gas”是 Centrica plc 或其子公司的商标。hive-mcp 基于社区编写 pyhiveapi 时积累的经验构建；该库是 Home Assistant Hive 集成的底层库。