Netatmo Energy

Netatmo Energy MCP

英语 | 法语

面向 Netatmo 智能恒温器和智能散热器阀门的 Netatmo MCP 服务。它让 AI 助手能够结构化地访问你的供暖数据：

• 房间温度和设定温度
• 供暖需求和锅炉活动
• 温度历史记录
• 确定性的供暖分析
• 每周供暖计划
• 可选的供暖控制：房间设定温度、离家／防冻模式和计划；每项更改都由你确认

它在你的设备上运行，且只与官方的 Netatmo Energy API 通信。默认情况下它是只读的：只有在登录时启用写入模式，它才能更改你的供暖设置。

它适用于任何可运行本地服务的 Model Context Protocol 客户端，与模型无关：

• Claude：Claude Desktop、Claude Code
• GPT / OpenAI：Codex CLI、VS Code + GitHub Copilot、Cursor
• Gemini：Gemini CLI、VS Code + GitHub Copilot
• Mistral 及其他模型：通过多模型客户端使用
• 本地大模型（Llama、Qwen、Mistral、DeepSeek、……）：LM Studio，以及通过 Goose、Continue、Cline、AnythingLLM、LibreChat 或 Open WebUI 使用 Ollama

它还适用于 Windsurf / Devin Desktop、Zed、Roo Code、Kilo Code、 JetBrains AI Assistant、Kiro 和 Warp。请参阅所有兼容的 AI 助手和 MCP 客户端。

网页版和移动版 ChatGPT 与 Claude 只接受远程 服务。要在这些平台上使用，请将可选的 远程服务部署到你自己的 Cloudflare 账户（免费计划）。

状态：早期发布版（0.3.2）。 Netatmo API 集成已在实际安装环境中 验证；欢迎提供反馈和设备报告。

为什么要做这个项目？

Netatmo 供暖系统会记录实用的数据：

• 每个房间的温度和设定温度
• 每个散热器阀门请求的供暖情况
• 锅炉何时收到供暖请求

这些数据被锁在 Netatmo 应用中，你可以查看，却无法就此提问。

本项目是 Netatmo Energy API 与任何兼容 MCP 的 AI 助手之间的小型桥梁。你可以用自然语言提问：“昨晚哪个房间最冷？”助手会调用一个精确的工具，并根据你的数据作答。它不会猜测。启用写入模式后，你还可以说：“把卧室设为 19 °C，直到早上 7 点”，然后确认更改。

其他少数 Netatmo MCP 服务面向 Netatmo 气象站。本项目则专为恒温器、散热器阀门和供暖历史记录打造。请参阅 docs/research.md 了解对比。

功能

• **设备发现：**住宅、房间、恒温器、智能散热器阀门、继电器 和网关。
• 当前状态
  • 每个房间：温度、设定温度、设定温度模式和供暖需求。
  • 锅炉开关状态和开窗检测。
  • 设备健康状况：电池、无线电 / Wi-Fi 信号、可达性。
• 历史记录
  • 房间温度和设定温度历史，分辨率从 30 分钟到 1 个月不等。
  • 锅炉活动历史（安装了 Netatmo 恒温器的设备）。
  • 较长时间范围的数据会分段获取并汇总，确保回答简洁。
  • 会报告数据缺失，不会填补缺失数据。
• **供暖分析。**这些数据通过确定性计算得出，不由 AI 模型计算。
  • 每个房间的统计数据。
  • 低于、处于或高于设定温度的时长。
  • 最大降温幅度和降温速率。
  • 房间排名。
  • 基于规则检测异常读数，并为每项标注严重程度和置信度。
• **每周计划：**时区（舒适、夜间、节能等）、每个时区的房间设定温度和时间表，以易读的日期和时间显示。
• 供暖控制（选择启用的写入模式）
  • 临时设置房间温度，始终会自动结束（默认 3 h，最长 24 h），或恢复计划。
  • 住宅模式：计划、外出或防冻保护，可选择设置截止日期。
  • 切换、创建、编辑和重命名每周计划。
  • 每项更改都会先预览，并且需要你明确确认。 默认温度范围限制为 7–28 °C。
• 15 个只读 MCP 工具、6 个供暖控制工具、4 个资源和 4 个 提示词（每日报告、异常检查、房间比较、供暖模式检查）。
• 简单设置
  • 通过单个 login 命令进行 OAuth2 浏览器登录。
  • 安全存储令牌并自动刷新。
  • doctor 可检查设置。

快速开始

你需要 Node.js 22.19 或更高版本，以及拥有 Energy 设备的 Netatmo 账户。

1. 创建免费的 Netatmo 开发者应用

1. 访问 https://dev.netatmo.com/apps，选择 创建。
2. 将重定向 URI设为 http://localhost:8977/callback。
3. 保留客户端 ID和客户端密钥，供第 2 步使用。

分步指南：docs/authentication.md。

2. 登录

npx -y netatmo-energy-mcp login

login 会要求你输入客户端 ID 和密钥，然后打开浏览器，让你在 netatmo.com 登录并批准只读访问权限。若要允许助手更改供暖设置，请改为运行 login --write（参见写入模式）。然后检查设置：

npx -y netatmo-energy-mcp doctor

**改为从源代码运行：**克隆代码库，运行 pnpm install && pnpm build，然后使用 node /path/to/netatmo-energy-mcp/dist/index.js 代替 npx -y netatmo-energy-mcp。

3. 连接 AI 助手

大多数客户端使用相同的 mcpServers JSON 配置块。Claude Desktop、Cursor、Windsurf / Devin Desktop、Cline、Roo Code、Kiro、 LM Studio、JetBrains AI Assistant、AnythingLLM、Warp 和 Gemini CLI 均可使用：

{
  "mcpServers": {
    "netatmo-energy": {
      "command": "npx",
      "args": ["-y", "netatmo-energy-mcp"]
    }
  }
}

命令行客户端：

# Claude Code
claude mcp add --transport stdio --scope user netatmo-energy -- npx -y netatmo-energy-mcp
# OpenAI Codex CLI
codex mcp add netatmo-energy -- npx -y netatmo-energy-mcp
# GitHub Copilot CLI
copilot mcp add netatmo-energy -- npx -y netatmo-energy-mcp

**Claude Code 插件。**无需运行 claude mcp add，只需安装插件：它 会添加服务以及一项技能，指导 Claude 如何诊断房间过冷、编写供暖报告并安全地更改供暖设置。在 Claude Code 中：

/plugin marketplace add christophe77/netatmo-energy-mcp
/plugin install netatmo-energy@netatmo-energy-mcp

参见 examples/claude-code。

**VS Code + GitHub Copilot。**将以下内容添加到 .vscode/mcp.json；注意 servers 键：

{
  "servers": {
    "netatmo-energy": { "type": "stdio", "command": "npx", "args": ["-y", "netatmo-energy-mcp"] }
  }
}

这些文件中都无需存放密钥：login 已将密钥保存到你的用户 配置文件夹中。各客户端的文件位置，以及 Zed、 Continue、Goose、LibreChat、Kilo Code、Msty 和 Open WebUI 的相关信息，见 examples/。

4. 提问

“现在每个房间的温度是多少？”

示例问题

这些是工具旨在回答的问题类型。助手会选择工具；下表显示了每个问题对应的工具。

问题	使用的工具
“我卧室的温度是多少？是否达到目标温度？”	netatmo_get_room_status
“锅炉现在正在运行吗？哪些房间正在请求供暖？”	netatmo_get_heating_status
“我的锅炉昨天运行了多久？”	netatmo_get_boiler_history
“显示过去 7 天客厅的温度。”	netatmo_get_temperature_history
“比较一下过去一周各个房间的情况。哪个房间降温最快？”	netatmo_compare_rooms
“昨晚我的供暖运行是否异常？”	netatmo_detect_anomalies
“生成昨天的供暖报告。”	提示词 heating_daily_report → netatmo_get_heating_summary
“有阀门电池电量不足吗？”	netatmo_get_device_status
“我的每周时间表是什么样的？”	netatmo_get_schedules
写入模式：“把办公室加热到 21 °C，持续 2 小时。”	netatmo_set_room_setpoint
写入模式：“我星期日晚上之前都不在家。”	netatmo_set_home_mode
写入模式：“把每间卧室的夜间区域温度降到 17 °C。”	netatmo_get_schedules → netatmo_update_schedule

锅炉的“运行时间”是指恒温器请求供暖的时长。Netatmo 不会测量燃气或能源消耗，因此本项目绝不会报告这些数据。

可用的 MCP 工具

只读工具仅需 read_thermostat OAuth 范围。包含参数和输出的完整参考文档由服务本身生成：docs/tools.md。

工具	描述
netatmo_list_homes	包含 Energy 设备的家居，以及房间和设备数量
netatmo_get_home	家居详情：供暖模式、计划、房间和设备
netatmo_list_rooms	房间及其 ID、类型和设备
netatmo_list_devices	恒温器、阀门、继电器：型号、房间、网关
netatmo_get_home_status	每个房间的当前状态、锅炉状态、警报
netatmo_get_room_status	一个房间的当前温度和设定点
netatmo_get_heating_status	锅炉开/关状态、请求供暖的房间
netatmo_get_device_status	电池、电信号、连接状态、固件
netatmo_get_temperature_history	房间温度历史记录，包含统计数据和缺失时段
netatmo_get_setpoint_history	房间设定点历史记录和设定点时段
netatmo_get_boiler_history	每小时/天/周的锅炉供暖需求时间
netatmo_get_heating_summary	按房间统计的舒适度指标，以及一段时间内的锅炉运行时间
netatmo_compare_rooms	房间指标和排名
netatmo_detect_anomalies	异常读数，包含严重程度、置信度和证据
netatmo_get_schedules	每周计划：分区、房间设定点、时间表

仅写入模式。 每项更改都需要你确认。

工具	描述
netatmo_set_room_setpoint	设置房间临时设定点或快速升温，或恢复为计划设定
netatmo_set_home_mode	计划、外出或防冻模式，可选持续至指定日期
netatmo_switch_schedule	启用另一个每周计划
netatmo_create_schedule	从现有计划复制并进行更改，以创建新计划
netatmo_update_schedule	按分区设置房间设定点、外出/防冻温度和时间表
netatmo_rename_schedule	重命名计划（实验性：未公开的端点）

资源：netatmo://homes 和 netatmo://homes/{homeId}/rooms、 …/devices 和 …/status。

写入模式（供暖控制）

写入模式默认关闭。要启用，请重新登录：

npx -y netatmo-energy-mcp login --write

这也会请求 write_thermostat OAuth 权限范围。重启 MCP 客户端后，供暖控制工具便会显示。

安全措施：

• 每项更改都由你确认。 支持 MCP elicitation 的客户端会直接向你确认。使用其他客户端时，首次调用只会返回预览和一次性令牌。助手必须向你展示预览，并在再次调用前获得你的同意。在此之前，不会向 Netatmo 发送任何内容。第二种流程依赖助手遵循其指令；设置 NETATMO_MCP_CONFIRM=elicitation，即可仅通过客户端显示的确认提示来允许更改。如果你的客户端取消每项更改，却不显示任何内容，请设置 NETATMO_MCP_CONFIRM=token。
• 限制。 温度必须保持在 7 到 28 °C 之间。手动设定值默认在 3 小时后结束，最长为 24 小时。使用 NETATMO_MCP_MIN_TEMP、NETATMO_MCP_MAX_TEMP 和 NETATMO_MCP_MAX_SETPOINT_HOURS 更改这些限制。
• 紧急开关。 即使使用启用了写入权限的登录，NETATMO_MCP_WRITE=0 也会强制进入只读模式。
• 审计日志。 每项已应用或失败的更改都会追加记录到配置文件夹中的 changes.log。
• 不会自动重试。 写入失败后绝不会盲目重发。

Netatmo 没有删除日程的 API：在此创建的日程只能在 Netatmo 应用中删除。重命名日程以及选择家庭模式为“日程”的日程会使用未公开的 Netatmo 参数，因此标记为实验性功能。详情： docs/configuration.md。

网页端和移动端（远程服务）

本地服务是最简单、隐私性最好的选择。若要在网页端和手机上的 ChatGPT 或 Claude 中控制供暖，请将相同的工具部署为在你自己的 Cloudflare 账户上运行的远程服务（免费套餐）：remote/README.md。

• 工具和安全措施相同。 默认只读；写入模式提供预览、确认，并采用相同的限制。
• 你的机密信息保留在自己的账户中。 Netatmo 应用凭据和令牌会在静态存储时加密，并保存在你的 Cloudflare 账户中。
• 助手通过 OAuth 登录。 你可以在授权页面使用所有者密码批准每个助手，也可以撤销授权。
• 只需一条命令即可关联你的家庭： npx netatmo-energy-mcp remote setup <your-worker-url>。
• 可选： 允许家人或朋友通过邀请码连接自己的 Netatmo 账户（ONBOARDING=invite）。每个账户只能看到自己的家庭。

已在 ChatGPT（桌面端和移动端）及 Claude（网页端、桌面端和移动端）中验证登录流程。设计文档：ADR-0013，ADR-0014。

支持的设备

设备	Netatmo 类型	状态
Smart Thermostat	NATherm1	已测试。 已在实际安装环境中验证 API（2026-10-08）
Smart Radiator Valve	NRV	已测试。 同一安装环境（6 个阀门）
Thermostat Relay	NAPlug	已测试。 同一安装环境
OpenTherm Modulating Thermostat / Gateway	OTM / OTH	预计可用，未经测试
BTicino Smarther with Netatmo	BNS	v0.1 不支持（可能需要 read_smarther 权限范围）

运行 netatmo-energy-mcp probe，并提交设备兼容性报告，帮助扩展此表。探测输出已清理敏感信息。

兼容的 AI 助手和 MCP 客户端

这是一个标准的本地（stdio）MCP 服务，因此不依赖于某一家 AI 厂商。任何能够启动本地服务的 MCP 客户端都可以使用它，并搭配该客户端运行的任意模型。

客户端	模型
Claude Desktop、Claude Code	Claude
OpenAI Codex CLI	OpenAI GPT 模型
Gemini CLI	Google Gemini
VS Code + GitHub Copilot（Agent 模式）、GitHub Copilot CLI	GPT、Claude、Gemini 和其他 Copilot 模型
Cursor、Windsurf / Devin Desktop、Zed、Warp、Kiro、JetBrains AI Assistant	多种托管模型
Cline、Roo Code、Kilo Code、Continue	多种模型，包括本地模型（Ollama、LM Studio）
LM Studio	本地开放模型：Llama、Qwen、Mistral、DeepSeek、…
Goose、AnythingLLM、LibreChat、Msty Studio	众多服务提供商，包括 Ollama
Open WebUI	通过 mcpo 代理使用 Ollama 等模型

各客户端的配置已根据官方文档核对： examples/。

Web 和移动端助手（ChatGPT 应用和连接器、Claude.ai 以及 Claude 和 ChatGPT 移动应用）只接受_远程_ MCP 服务。请为它们使用远程服务。尚未测试 Mistral Le Chat。

**测试。**本服务已使用官方 MCP SDK 客户端和 MCP Inspector 进行测试。小型本地模型的工具调用质量因模型而异。如遇到特定客户端的问题，请报告。

身份验证

本项目使用 Netatmo 的 OAuth2 授权码流程。你在 netatmo.com 上登录；此工具不会获取你的 Netatmo 密码。

**权限范围。**默认情况下只请求 read_thermostat，因此即使令牌泄露，也无法更改供暖设置。login --write 还会请求 write_thermostat。

**你自己的应用。**每位用户都需注册一个免费的 Netatmo 开发者应用。客户端密钥不能随开源代码一起发布。

**刷新。**访问令牌会自动刷新。多个 MCP 客户端同时运行时，会通过锁文件协调，避免令牌互相失效。

详情：docs/authentication.md。

隐私与安全

**哪些数据会离开你的设备。**只有发往 api.netatmo.com 的 HTTPS 请求。在只读模式下，请求只会访问 4 个读取端点：客户端会在访问网络前拒绝任何写入操作，测试也会对此进行验证。在写入模式下，只有在你确认后才会发送更改。

哪些数据保留在本地。

• 凭据保存在用户配置文件夹中的 credentials.json 里，仅你的账户可读取（macOS/Linux 上权限为 0600；Windows 上使用受限 ACL）。
• 不收集遥测数据，不进行分析，也不使用第三方服务。
• 服务通过 stdio 与 MCP 客户端通信，不会开放网络端口。

**你的 AI 服务提供商。**工具返回的数据会由你使用的助手读取，因此会由该模型提供商处理。

**不返回账户数据或位置。**你的电子邮件和家庭坐标永远不会被返回。

了解更多：

• 安全模型
• 预发布安全审查
• 报告漏洞
• 隐私政策

架构

Netatmo 客户端和分析功能独立于 MCP。设计决策记录在 ADR 中，docs/architecture.md 描述了各层。

限制

这些限制源于 Netatmo Energy API；详情请参阅 docs/api-capabilities.md。

• 不提供能源或燃气消耗数据。 锅炉活动以热量_需求_时间表示。使用聚合数据时，无法得知燃烧器循环次数。
• 不提供阀门供暖需求的历史记录。 该数据仅作为当前值提供。未来可选择启用的收集器或许会记录这类数据（ADR-0011）。
• Energy API 不提供室外温度。 计划在 v0.4 中加入天气信息。
• 历史记录的最高分辨率为 30 分钟。 每次请求最多返回 1024 个值，因此较长的时间范围会使用更粗略的时间尺度。
• 文档中的部分内容与 API 不符。 实时数据显示，锅炉测量值的单位是秒，而非文档中所述的分钟。本项目会进行转换。
• 速率限制。 Netatmo 会限制每位用户和每个应用的请求次数。服务会自行限流，并缓存拓扑结构和当前状态。

路线图

版本	重点
v0.1	只读 MCP 服务
v0.2	日程安排、选择性启用供暖控制
v0.3	面向 Web 和移动设备的远程服务（当前版本）
v0.3.x	更丰富的诊断信息
v0.4	天气信息（Open-Meteo）
v0.5–v0.7	热建模、预测、数字孪生
v1.0	稳定的接口

默认情况下永远不会启用写入模式。 请参阅 docs/roadmap.md。

贡献

欢迎提交 Bug 报告、设备兼容性报告和拉取请求。 请参阅 CONTRIBUTING.md 了解如何设置项目。项目使用模拟的 API 响应运行：无需 Netatmo 账户。请遵守行为准则。

许可证

Apache-2.0

免责声明

这是一个独立的开源项目，与 Netatmo 或 Legrand 无关，也未获其认可或赞助。“Netatmo”是其所有者的商标，在此仅用于说明兼容性。使用风险由您自行承担；供暖安全绝不能依赖 AI 助手。