iaqualink-mcp

iaqualink-mcp

适用于 iAqualink（Zodiac / Jandy / Fluidra）泳池和水疗设备的 MCP 服务。 读取温度、设定值、水泵、加热器、灯、辅助电路和盐氯发生器状态，并切换设备——每项更改都需确认，并通过重新读取进行验证。使用你自己的 iAqualink 账户登录（与 iAqualink 应用使用相同的电子邮件和密码）；无需浏览器、扩展或桥接程序。

支持参考客户端支持的两种系统类型：iAqua （Jandy iAquaLink 控制面板）和 eXO（Zodiac 盐氯发生器）。账户上的其他设备类型（机器人清洁器等）会列出，但无法控制。

状态：部分经过实际验证。 请求格式来自 iaqualink-py 0.7.0（Home Assistant 使用的版本）和 WebTouch 捕获记录（参见 docs/IAQUALINK-API.md）。

• **已在真实 iAqua（RS）控制面板上验证可用，2026-10-11/12：**登录、系统列表（devices.json）、iAqua 状态读取（get_home、 get_devices）和 WebTouch（位置查询、初始化、按钮按下及显示流）。
• **仍为推导所得，尚未进行实际验证：**iAqua set_* 命令（水泵、 加热器、辅助电路、灯、温度）、所有 eXO 请求（影子读取和写入）、iaqualink_set_chlorinator 推断的请求格式，以及 iQ20 计划任务 回退方案。每次写入仍会重新读取，以确认实际结果。

本项目由 AI（Claude Code）开发并维护。请自行斟酌使用。

工具

工具	功能	注释
iaqualink_list_systems	账户中的系统及其序列号	读取
iaqualink_get_status	温度、设定点、水泵、加热器、辅助设备/灯光、氯化器、盐度/pH/ORP（view：compact · full · raw）	读取
iaqualink_healthcheck	是否已配置并通过验证的登录信息	读取
iaqualink_set_equipment	泳池/SPA 水泵、泳池/SPA/太阳能加热器；eXO 过滤泵、产量、增强、低档、加热 — 开/关	写入，不具破坏性
iaqualink_set_aux	辅助电路或灯光开/关（按编号、aux_<n> 或标签）	写入，不具破坏性
iaqualink_set_light	可调光亮度（0/25/50/75/100）或颜色效果（iAqua）	写入，不具破坏性
iaqualink_set_temperature	泳池和/或 SPA 设定点（iAqua °F/°C；eXO 泳池用 °C）	写入，不具破坏性
iaqualink_set_chlorinator	eXO 氯化器输出百分比 — 推断的结构，不在 iaqualink-py 中	写入，不具破坏性
iaqualink_list_schedules	通过 WebTouch 获取 RS 面板程序（iAqua；iQ20 回退探测）；eXO 定时器	读取
iaqualink_add_schedule	通过 WebTouch 添加 RS 面板程序（电路、开始时间、停止时间、运行日期）	写入，不具破坏性
iaqualink_edit_schedule	通过 WebTouch 更改 RS 面板程序的开始时间/停止时间/运行日期	写入，不具破坏性
iaqualink_delete_schedule	通过 WebTouch 删除 RS 面板程序 — 无法撤销	写入，有破坏性
iaqualink_set_schedule	设置/重新安排/停用 eXO 定时器（开始–停止时间；变速水泵的转速）— 仅限 eXO，未经实时验证	写入，不具破坏性
iaqualink_check_panel	RS 系统是否在线，以及面板当前显示什么（屏幕、打开的对话框、存在未保存更改的编辑模式）？当应用与这些工具报告不一致时运行此工具	读取
iaqualink_list_pump_speeds	通过 WebTouch 获取 RS 面板变速水泵的命名转速、对应 RPM 及当前运行的转速	读取
iaqualink_set_pump_speed	通过 WebTouch 让水泵以指定转速运行	写入，不具破坏性
iaqualink_set_pump_speed_rpm	通过 WebTouch 更改指定转速的 RPM（600–3450）；尚未运行的转速会短暂运行以完成设置，然后恢复原先运行的转速	写入，不具破坏性
iaqualink_list_onetouch	通过 WebTouch 获取 RS 面板 OneTouch 场景（Spa Mode、All OFF、…）及其状态	读取
iaqualink_set_onetouch	通过 WebTouch 开/关 OneTouch 场景 — 尚未进行实时切换测试	写入，不具破坏性

此工具集中的每个写入操作都有对应的逆操作，且不会影响其他人 — 但删除面板程序除外：面板会立即保存删除操作，且无法撤销，因此该操作标记为有破坏性。

Jandy AquaLink RS 面板上的定时计划和 OneTouch通过 WebTouch 执行；WebTouch 是 iAqualink Web 应用使用的面板模拟功能：服务端打开面板的显示流，按下与用户相同的按钮（每次按下前都会检查面板是否处于预期屏幕和行，否则中止），返回 Home，然后重新读取以验证。每个系统一次只能运行一个 WebTouch 会话。添加/编辑/删除操作序列依据 RS 面板上的实时录制（2026-10-11）— 参见 docs/IAQUALINK-API.md。 如果 WebTouch 不可用，iaqualink_list_schedules 会回退到 iQ20 定时计划（适配器固件 3+），每种方式各探测一次：r-api.iaqualink.net/v2（Bearer）、p-api.iaqualink.net/v2（Bearer）、p-api.iaqualink.net/v2（裸令牌）和 prm.iaqualink.net/v1（裸令牌），并报告每次尝试。 iQ20 定时计划的写入功能尚未实现。 写入操作的工作方式。 它会先读取当前状态；如果状态已匹配，就不会发送任何内容——iAqua 的泵、加热器和辅助设备命令都是切换操作，因此盲目发送会改变设备当时的状态。接着它会请求你确认（客户端支持时会显示一个征询提示词；否则会提供预览和一个 confirmToken，该令牌绑定到计划操作所依据的状态），然后发送命令，并重新读取状态，直到显示出请求的值。结果为 confirmed、unchanged 或 sent-unconfirmed，并附带观察到的状态（eXO 会异步应用更改——请再次检查，而不是重试）。

设置

npm i -g @chrischall/iaqualink-mcp

变量	必需	含义
IAQUALINK_EMAIL	每个工具都必需	你的 iAqualink 应用登录邮箱
IAQUALINK_PASSWORD	每个工具都必需	你的 iAqualink 密码（不会去除首尾空格）
IAQUALINK_STATUS_CACHE_SECONDS	否	状态读取结果的复用秒数（默认值为 5；设为 0 可禁用）
IAQUALINK_WEBTOUCH_STREAM_HOSTS	否	WebTouch 显示流可能来自的其他主机（以逗号分隔）；默认仅为 prm.iaqualink.net
MCP_CONFIRM_MODE	否	ask-user（默认）/ auto / refuse
MCP_CONFIRM_TTL_SECONDS	否	confirmToken 的有效期（默认值为 600）
MCP_CONFIRM_ELICITATION	否	设为 off 后，即使客户端声明支持征询，也会跳过提示

服务启动时无需凭据（因此宿主可以列出其工具），首次调用时会报告缺少凭据。密码被拒绝后绝不会重试：拒绝状态会一直保留到服务重启，因此输错密码不会导致账户被锁定。

Claude Code：claude mcp add iaqualink -e IAQUALINK_EMAIL=… -e IAQUALINK_PASSWORD=… -- npx -y @chrischall/iaqualink-mcp

托管版（claude.ai）

mint.yaml 为每位用户声明独立子进程，并在连接器的授权页面提供邮箱/密码表单（每个人都以自己的身份登录）；出站访问范围严格限定为 prod.zodiac-io.com、r-api.iaqualink.net、p-api.iaqualink.net（仅用于 iQ20 探测）和 prm.iaqualink.net（用于 WebTouch 和 iQ20 探测）。除非将其他主机添加到 IAQUALINK_WEBTOUCH_STREAM_HOSTS（并加入出站访问范围），否则 WebTouch 显示流会被拒绝。没有持久化状态——会话存储在内存中，冷启动后重新登录即可重建会话。

技能

• skills/iaqualink — 如何使用这些工具。
• skills/iaqualink-curl — 使用 curl 在 shell 中直接执行相同的读取操作，凭据来自 macOS 钥匙串（登录、系统列表和 iAqua 读取均为实时获取；eXO 影子读取仍由 iaqualink-py 推导）。

开发

npm install
npm run build
npm run test:coverage   # typecheck (src + tests) + vitest, 100% coverage — what CI runs

测试会使用基于 iaqualink-py 测试样例构建的内存中 iAqualink（tests/support/fake-server.ts），通过真实客户端运行。