About iaqualink-mcp
An MCP server for iAqualink pool and spa systems, aimed at equipment owners who want to inspect and control their setup. It reads system state and gates changes behind confirmation, then checks the result with a fresh read.
Key features
- 01Read temperatures and equipment state
- 02Control pumps, heaters, lights, and circuits
- 03Adjust temperature set points
- 04Manage schedules and OneTouch scenes
- 05Confirm changes and verify by re-reading
Use cases
- 01Check pool and spa equipment status
- 02Turn pumps, heaters, or lights on or off
- 03Adjust pool or spa temperature targets
- 04Review or change supported schedules
MCP support
Exposes iAqualink account and equipment status and control tools to MCP clients. Equipment changes require confirmation and are verified by reading the state again.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @chrischall/iaqualink-mcpIAQUALINK_EMAILThe email address you sign in to the iAqualink app with (needed by every tool; the server starts without it)IAQUALINK_PASSWORDSecretYour iAqualink password (needed by every tool; the server starts without it)IAQUALINK_STATUS_CACHE_SECONDSSeconds a system's status read is reused before re-polling iAqualink (default 5; 0 disables)IAQUALINK_WEBTOUCH_STREAM_HOSTSExtra hosts (comma-separated) the WebTouch display stream may be served from, beyond webtouch.iaqualink.net and prm.iaqualink.net. Leave unset unless a WebTouch error names a new hostLocal servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
8Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| view | enum | No | Response shape: "compact" (default) drops fields the response already carries elsewhere; "full" returns every field this server understands; "raw" returns the upstream payload unprojected. compact = normalized status; full = plus aux/light details and the unprocessed entries; raw = iAqualink’s responses untouched.compact | full | raw |
Details
From the project READMEiaqualink-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
| Tool | What it does | Annotation |
|---|---|---|
iaqualink_list_systems | Systems on the account and their serials | read |
iaqualink_get_status | Temperatures, set points, pumps, heaters, aux/lights, chlorinator, salinity/pH/ORP (view: compact · full · raw) | read |
iaqualink_healthcheck | Whether a sign-in is configured and accepted | read |
iaqualink_set_equipment | Pool/spa pump, pool/spa/solar heater; eXO filter pump, production, boost, low, heating — on/off | write, not destructive |
iaqualink_set_aux | Aux circuit or light on/off (by number, aux_<n> or label) | write, not destructive |
iaqualink_set_light | Dimmable brightness (0/25/50/75/100) or color effect (iAqua) | write, not destructive |
iaqualink_set_temperature | Pool and/or spa set point (iAqua °F/°C; eXO °C pool) | write, not destructive |
iaqualink_set_chlorinator | eXO chlorinator output % — inferred shape, not in iaqualink-py | write, not destructive |
iaqualink_list_schedules | RS panel programs via WebTouch (iAqua; iQ20 fallback probe); eXO timers | read |
iaqualink_add_schedule | Add an RS panel program (circuit, start, stop, run days) via WebTouch | write, not destructive |
iaqualink_edit_schedule | Change an RS panel program's start / stop / run days via WebTouch | write, not destructive |
iaqualink_delete_schedule | Delete an RS panel program via WebTouch — no undo | write, destructive |
iaqualink_set_schedule | Set / re-time / disable an eXO timer (start–stop, rpm on variable-speed pumps) — eXO only, unverified live | write, not destructive |
iaqualink_check_panel | Is an RS system online, and what is its panel showing (screen, open dialog, Edit mode with unsaved changes)? Run it when the app and these tools disagree | read |
iaqualink_list_pump_speeds | RS panel variable-speed pump: the named speeds, their RPM and which one runs, via WebTouch | read |
iaqualink_set_pump_speed | Run the pump at a named speed via WebTouch | write, not destructive |
iaqualink_set_pump_speed_rpm | Change a named speed's RPM (600–3450) via WebTouch; a speed that is not running runs briefly while set, then the running speed is restored | write, not destructive |
iaqualink_list_onetouch | RS panel OneTouch scenes (Spa Mode, All OFF, …) and their state, via WebTouch | read |
iaqualink_set_onetouch | Turn a OneTouch scene on/off via WebTouch — toggle not exercised live yet | write, not destructive |
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
| Variable | Required | Meaning |
|---|---|---|
IAQUALINK_EMAIL | for every tool | Your iAqualink app sign-in email |
IAQUALINK_PASSWORD | for every tool | Your iAqualink password (not trimmed) |
IAQUALINK_STATUS_CACHE_SECONDS | no | Seconds a status read is reused (default 5; 0 disables) |
IAQUALINK_WEBTOUCH_STREAM_HOSTS | no | Extra hosts (comma-separated) the WebTouch display stream may come from; default only prm.iaqualink.net |
MCP_CONFIRM_MODE | no | ask-user (default) / auto / refuse |
MCP_CONFIRM_TTL_SECONDS | no | confirmToken lifetime (default 600) |
MCP_CONFIRM_ELICITATION | no | off skips the prompt even on clients that declare elicitation |
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 withcurl, 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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.