Iaqualink MCP

iaqualink-mcp

MCP server for iAqualink (Zodiac / Jandy / Fluidra) pool and spa equipment. Read temperatures, set points, pumps, heaters, lights, aux circuits and salt chlorinator state, and switch equipment — every change confirmation-gated and verified by a re-read. It signs in with your own iAqualink account (the same email and password as the iAqualink app); no browser, extension or bridge.

Supports the two system types the reference client supports: iAqua (Jandy iAquaLink panels) and eXO (Zodiac salt chlorinators). Other device types on the account (robotic cleaners, …) are listed but not controlled.

Status: partly verified live. Request shapes come from

iaqualink-py 0.7.0 (what Home

Assistant uses) and a WebTouch capture (see

docs/IAQUALINK-API.md).

- Seen working on a real iAqua (RS) panel, 2026-10-11/12: sign-in, the

system list (devices.json), the iAqua status reads (get_home,

get_devices) and WebTouch (location lookup, init, button presses and the

display stream).

- Still derived, not yet exercised live: the iAqua set_* commands (pump,

heater, aux, light, temperature), every eXO request (shadow read and

writes), iaqualink_set_chlorinator's inferred shape, and the iQ20 schedule

fallback. Every write still re-reads to confirm what happened.

This project was developed and is maintained by AI (Claude Code). Use at your own discretion.

Tools

Systems by name. At start the server lists the account's systems once; when that works, every serial argument advertises the supported systems' names (e.g. "Pool", "Spa") as an enum, and every tool accepts a name or a serial — an unknown name is refused with the list of known systems. If the listing fails (no sign-in yet, iAqualink down, past 5 s), the argument is a plain serial and nothing else changes. Every tool also carries _meta.mint hints (domain home; lookup for reads, turn-on-off for the set_* switches, change for schedule edits) that mcp-host's context groups read and other clients ignore.

Every write has an inverse in this set and reaches no other person — except deleting a panel program, which the panel stores immediately with no undo, so that one is marked destructive.

Schedules and OneTouch on a Jandy AquaLink RS panel go through WebTouch, the panel emulation the iAqualink web app uses: the server opens the panel's display stream, presses the same buttons a person would (checking before every press that the panel is on the expected screen and row, and aborting otherwise), returns to Home, and re-reads to verify. Only one WebTouch session per system runs at a time. The add / edit / delete sequences follow a live capture on an RS panel (2026-10-11) — see docs/IAQUALINK-API.md. If WebTouch is unavailable, iaqualink_list_schedules falls back to iQ20 schedules (adapter firmware 3+), probing r-api.iaqualink.net/v2 (Bearer), p-api.iaqualink.net/v2 (Bearer), p-api.iaqualink.net/v2 (bare token) and prm.iaqualink.net/v1 (bare token) once each and reporting every attempt. iQ20 schedule *writes* are not built.

How a write works. It reads the current state first and sends nothing if it already matches — iAqua's pump/heater/aux commands are *toggles*, so a blind send would flip whatever the state happened to be. It then asks you to confirm (an elicitation prompt where the client supports one; otherwise a preview plus a confirmToken, bound to the state it was planned against), sends, and re-reads until the requested value shows up. The result is confirmed, unchanged, or sent-unconfirmed with what was observed (eXO applies changes asynchronously — check again rather than retrying).

Setup

npm i -g @chrischall/iaqualink-mcp

The server starts without credentials (so hosts can list its tools) and reports them missing on the first call. A rejected password is never retried: the refusal is remembered until the server restarts, so a typo cannot lock the account.

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

Hosted (claude.ai)

mint.yaml declares per-user children with an email/password form on the connector's authorize page (each person signs in as themselves), egress to exactly prod.zodiac-io.com, r-api.iaqualink.net, p-api.iaqualink.net (iQ20 probe only) and prm.iaqualink.net (WebTouch, and the iQ20 probe); the WebTouch display stream is refused on any other host unless it is added to IAQUALINK_WEBTOUCH_STREAM_HOSTS (and egress). No persistent state — the session lives in memory and one sign-in rebuilds it after a cold start.

Skills

• skills/iaqualink — how to use these tools.
• skills/iaqualink-curl — the same reads straight from a shell with curl, credentials from the macOS Keychain (the sign-in, system list and iAqua reads are seen live; the eXO shadow read is still derived from iaqualink-py).

Development

npm install

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

Tests run the real client against an in-memory iAqualink (tests/support/fake-server.ts) built from iaqualink-py's fixtures.