iZone CLI & MCP Server

Control your iZone ducted air conditioning system from the terminal and through any MCP-compatible AI assistant.

Setup

No dependencies required beyond Python 3. The CLI and MCP server use only the standard library for iZone communication. The MCP server additionally requires the mcp package.

# Install MCP SDK (for the MCP server only)
pip3 install mcp

# Make the CLI available globally
ln -sf /path/to/izone-cli/izone /opt/homebrew/bin/izone

CLI Usage

# Full status (system + zones, default if no command given)
izone status

# System info only (no zones)
izone system

# List all zones
izone zones

# Power
izone on
izone off

# Mode: cool, heat, vent, dry, auto
izone mode cool

# Fan speed: low, medium, high, auto, top
izone fan auto

# System temperature (15.0 - 30.0 C)
izone temp 22

# Sleep timer
izone sleep 60                        # Auto-off in 60 minutes
izone sleep 0                         # Clear timer

# Zone control (by index)
izone zone 2                          # View zone info
izone zone 2 --mode auto             # Set zone to auto
izone zone 2 --temp 23               # Set zone temperature
izone zone 5 --max-air 80            # Set max airflow
izone zone 5 --mode auto --temp 22   # Combine options

# Air quality readings (humidity, eCO2, TVOC)
izone airquality

# Save and restore default settings
izone defaults save                   # Snapshot current settings
izone defaults show                   # View saved defaults
izone defaults restore                # Restore saved defaults

# Profiles (named presets for optimal settings)
izone profiles                        # List all profiles
izone profile save bedtime            # Save current settings as "bedtime"
izone profile apply bedtime           # Apply "bedtime" profile
izone profile set cool-night --mode cool --fan low --temp 23 --zones "2:22,5:23"
izone profile show cool-night         # View profile details
izone profile delete old-one          # Delete a profile

# Schedules / scenes
izone schedules                       # List all schedules
izone schedule 2                      # View schedule details
izone schedule 0 --name "Cool"        # Rename
izone schedule 0 --mode cool --fan auto
izone schedule 0 --start 07:30 --stop 22:00
izone schedule 0 --days weekdays      # M,Tu,W,Th,F,Sa,Su,weekdays,weekends,all
izone schedule 0 --enable yes         # Enable schedule
izone run 2                           # Run schedule now (as a scene)

# JSON output (for scripting)
izone json

# Network discovery
izone discover

# Target a specific bridge IP (skips discovery)
izone --ip 192.168.1.100 status

MCP Server

The MCP server lets any MCP-compatible AI assistant control your AC through natural language.

Configuration

Works with Claude Code, OpenAI Codex, OpenClaw, and any MCP-compatible client. See docs/mcp-server.md for configuration for each platform.

Example for Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "izone": {
      "command": "python3",
      "args": ["/path/to/izone-cli/izone_mcp_server.py"],
      "env": {}
    }
  }
}

Restart your MCP client after adding the configuration.

Available Tools

Tool	Description
izone_status	Full system and zone readout
izone_power	Turn system on or off
izone_mode	Set operating mode
izone_fan	Set fan speed
izone_temperature	Set system target temperature
izone_zone_control	Control individual zones (mode, temp, airflow)
izone_comfort_setup	Quick setup: power on, set mode/fan/temp, open specific zones
izone_profiles	List all saved profiles
izone_apply_profile	Apply a named profile (mode, fan, temp, zones)
izone_save_profile	Save current settings as a named profile
izone_create_profile	Define a profile from parameters without changing the AC
izone_insights	Health/efficiency review: struggling zones, free-cooling, air quality
izone_recommend	Weather-aware plan (mode/temp/zones) — report it or apply it
izone_history	Per-zone temperature trends and sparklines from logged snapshots
izone_set_location	One-time home location setup for outdoor-weather features
izone_sleep	Sleep timer (auto-off after N minutes)
izone_defaults_save / izone_defaults_restore	Snapshot and restore normal settings
izone_schedules / izone_schedule_detail / izone_schedule_edit / izone_run_schedule	Schedule management

Example Prompts

• "What's the temperature in my house?"
• "Turn on the AC and cool the study to 23 degrees"
• "Cool the master bedroom and lounge to 22, close everything else"
• "Turn off the AC"
• "Set the fan to low and drop the temp to 21"

Intelligence

The MCP server keeps a local history and understands the weather:

• Every full status poll appends a snapshot (system, zones, outdoor temp) to ~/.config/izone/history.jsonl (auto-rotated at ~4MB). izone_history turns it into per-zone trends; izone_insights uses it to spot zones that chronically miss setpoint.
• Set a home location once with izone_set_location ("Perth") and status, insights, and recommendations become outdoor-aware: free-cooling detection (vent mode when it's cooler outside), pre-cooling/pre-heating ahead of forecast peaks, and smarter mode selection. Weather comes from Open-Meteo (free, no API key); with no location configured, all weather features silently skip. Config lives in ~/.config/izone/config.json.
• Vent-mode free cooling is opt-in: most ducted systems recirculate indoor air, so vent only helps if yours has a fresh-air intake. Set "fresh_air": true in ~/.config/izone/config.json to let recommendations use vent automatically; without it they suggest opening windows instead. Vent is never chosen when outdoor air is below 14C, and the fan is capped at medium overnight.
• Safety rails: constant (pressure-relief) zones are never closed, open/close-only zones never get a setpoint, and implausible sensor readings (dead sensor reporting 0.0C) are excluded from decisions rather than acted on.
• izone_recommend composes it all into one plan — occupied zones, target temp, mode, fan — and can apply it (saving defaults first so it's reversible).

Bridge Discovery

The CLI auto-discovers your iZone bridge via UDP broadcast and caches the IP at ~/.config/izone/bridge_ip for one hour. Use --ip to skip discovery and target a bridge directly.

Reliability Defaults

Both the CLI and MCP server now protect the bridge from burst traffic:

• HTTP requests are serialized and paced with a minimum 250 ms gap.
• Transient transport failures (timeouts/socket errors) are retried automatically.
• Transient bridge responses like {ERROR}/{BUSY} are retried automatically.

Optional environment variables:

• IZONE_HTTP_MIN_GAP (default 0.25) - minimum seconds between HTTP requests
• IZONE_HTTP_RETRIES (default 4) - max attempts for one request/command
• IZONE_HTTP_RETRY_DELAY (default 0.25) - base backoff between retries

Docs

• Architecture — system design and request flows
• iZone Protocol — full V2 API reference
• MCP Server — MCP tools and configuration