rachio-mcp

An MCP (Model Context Protocol) server for Rachio sprinkler controllers, built on the reverse-engineered Android-app gRPC API.

The public Rachio API exposes only read-only access to schedules and a handful of single-action endpoints. This server instead talks to the same internal gRPC backend (cloud.rach.io:443) that the official mobile app uses, giving an agent the full set of operations: listing devices and zones, inspecting schedules, creating and previewing new schedules, updating and deleting them, starting and stopping manual zone runs, setting rain delays, and more.

⚠️ Unofficial. This server uses a reverse-engineered API. It works as of Rachio Android v4.21.18 and is not supported by Rachio. The schema can change without notice.

Features

• Devices and zones — list controllers, sensors, and weather stations; inspect zone soil/nozzle/plant configuration and live state
• Schedules — list, read, preview (dry-run), create, update, delete, copy, run, and skip schedules
• Live control — stop watering, run specific zones manually, set rain delays, skip/pause/resume the currently-running zone
• Context — calendar of upcoming and past runs, active alerts, observed/forecast weather readings

Quick Start

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Mint a long-lived access token

The MCP server itself never sees your Rachio password. Instead you mint a long-lived (~25-year) access token once, and supply only the token to the MCP client.

uvx --from rachio-mcp rachio-mcp-token

It will prompt for your Rachio email and password, then print a RACHIO_ACCESS_TOKEN value to paste into your MCP client config. The token remains valid until you change your password or explicitly log out from another device.

Or, if you'd rather have the commands on your PATH permanently, install once:

uv tool install rachio-mcp

Then rachio-mcp-token (and rachio-mcp itself) are available as regular commands.

For scripting (e.g. pipe into a password manager):

[email protected] RACHIO_PASSWORD=... \
    uvx --from rachio-mcp rachio-mcp-token --json | jq .access_token

3. Configure your MCP client

uvx downloads and runs the server on demand — no separate install step required.

OpenCode (opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rachio": {
      "type": "local",
      "command": ["uvx", "rachio-mcp"],
      "environment": {
        "RACHIO_ACCESS_TOKEN": "{env:RACHIO_ACCESS_TOKEN}"
      },
      "enabled": true
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "rachio": {
      "command": "uvx",
      "args": ["rachio-mcp"],
      "env": {
        "RACHIO_ACCESS_TOKEN": "paste-your-token-here"
      }
    }
  }
}

If a tool call later returns a "token rejected" error, rerun rachio-mcp-token to mint a fresh one and update the config.

Available Tools

23 tools over stdio transport.

Discovery

Schedule CRUD

Live controller ops

All device_id, zone_id, schedule_id, and location_id parameters are UUIDs obtained from the list_* tools. Dates use YYYY-MM-DD (or MM-DD for annual-recurring schedules); times use HH:MM.

Recommended Workflow for Schedule Changes

1. list_devices → pick your controller
2. list_zones(device_id=...) → note each zone's id and zone_number
3. list_schedules(device_id=...) and get_schedule(schedule_id=...) → understand what's already configured
4. preview_schedule(...) → dry-run your proposed schedule. Read the returned summary string and the per-zone breakdown
5. create_schedule(...) (same arguments) → commit
6. get_schedule(schedule_id=<new>) → confirm
7. delete_schedule(schedule_id=<new>) → rollback if needed

preview_schedule is safe to call repeatedly — it never writes anything.

To edit an existing schedule instead of recreating it, use update_schedule. It performs a partial merge: read the schedule with get_schedule, then pass only the fields you want to change (name, enabled, timing/criteria, days, or zones/zone_ids_to_remove). Omitted fields are left untouched.

How It Works

This server talks to cloud.rach.io:443 over TLS-protected gRPC, the same backend used by the Rachio Android app. Authentication uses the OAuth 2 password grant against oauth.rach.io/oAuth/token with the Android app's hardcoded client credentials.

The gRPC .proto definitions were recovered by decompiling the Rachio Android APK (v4.21.18) with jadx, extracting the embedded FileDescriptorProto payloads from the generated Java classes, and round-tripping them through protoc to produce clean .proto source. Pre-compiled Python stubs for the 40-odd messages/services used by the 23 MCP tools ship in src/rachio_mcp/proto/.

Regenerate those stubs any time the app's proto surface changes:

scripts/build_protos.sh

The stub generator reads from reverse-engineering/protos/, which is not shipped in the wheel but is kept alongside the source for future updates.

Python API

The MCP server wraps a standalone client you can use directly:

from rachio_mcp import RachioClient

c = RachioClient()

# Discovery
for d in c.list_devices():
    print(d["type"], d["id"], d.get("name"))

# Preview a proposed schedule
preview = c.preview_schedule(
    name="Fall Lawn",
    schedule_type="FIXED",
    zones=[
        {"device_id": "<controller>", "zone_id": "<zone>", "watering_time": 1200},
    ],
    start_time="06:00",
    days=["WED"],
    annual_start="09-16",
    annual_end="11-15",
    smart_cycle=True,
)
print(preview["summary"])

# Commit
created = c.create_schedule(name="Fall Lawn", ...)
print("created", created["id"])

# Rollback
c.delete_schedule(created["id"])

The client reads RACHIO_ACCESS_TOKEN from the environment, derives the user's user_id lazily on first use (via LocationService.ListLocations), and keeps both in memory for the lifetime of the process. Nothing is written to disk.

Environment

Minting a token (one-time setup)

Neither RACHIO_EMAIL nor RACHIO_PASSWORD is ever read by the MCP server itself — they exist only to feed the one-time token-mint CLI.

Transport

stdio only. Remote HTTP with OAuth 2.1 is not supported in v0.1.

License

MIT — see LICENSE.