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

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"

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