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: built from the open-source client, live verification pending.
Every request shape is transcribed from
iaqualink-py 0.7.0 (what Home
Assistant uses) — see docs/IAQUALINK-API.md — and has
not yet been exercised against a real pool. The login endpoint and app key
are confirmed live.
This project was developed and is maintained by AI (Claude Code). Use at your
own discretion.
| 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 |
Every write has an inverse in this set and reaches no other person, so none is
marked destructive.
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) |
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 and r-api.iaqualink.net, and 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 (derived from iaqualink-py; live
verification pending).
Development
npm install
npm run build
npm run test:coverage
Tests run the real client against an in-memory iAqualink
(tests/support/fake-server.ts) built from iaqualink-py's fixtures.