rachio-mcp 0.1.0

MCP server for Rachio sprinkler controllers using the reverse-engineered mobile gRPC API

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.

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

RACHIO_EMAIL=[e-mail] 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

Tool	Description
list_devices	Every device on the account — controllers, sensors, weather stations
get_device	Full details + live state for a single device
list_zones	Zones configured on a controller, with agronomic metadata
get_zone	Full detail for a single zone
get_calendar	Scheduled runs + skip events for a date range
get_active_alerts	Unresolved alerts on a device or zone
get_weather	Observed + forecast weather readings for a location

Schedule CRUD

Tool	Description
list_schedules	Filter by device, location, zone, or schedule id
get_schedule	Single schedule + its locations/devices
preview_schedule	Dry-run — returns the Schedule that create_schedule would produce, including the server-generated human-readable summary. Never persists
create_schedule	Create a new schedule
update_schedule	Rename or toggle enabled/disabled
delete_schedule	Permanent, destructive
copy_schedule	Duplicate an existing schedule
run_schedule	Trigger an immediate run
skip_schedule	Skip or re-arm the next scheduled run
get_schedule_runs	Past runs + skip events for a schedule

Live controller ops

Tool	Description
stop_watering	Stop whatever is running
start_zones	Start one or more zones manually by zone number + duration
set_rain_delay	Defer all schedules until a given time
skip_current_zone	Skip to the next zone in the active run
pause_watering	Pause the current zone for N seconds
resume_watering	Resume a paused run

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.

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

Variable	Required	Description
RACHIO_ACCESS_TOKEN	Yes	Long-lived bearer token minted by rachio-mcp-token. Valid for ~25 years unless revoked.
LOG_LEVEL	No	Python logging level (default: INFO). Logs go to stderr; stdio transport's stdout is reserved for the MCP protocol.

Minting a token (one-time setup)

Variable	Used by	Description
RACHIO_EMAIL	rachio-mcp-token only	Rachio account email. If unset, rachio-mcp-token prompts interactively.
RACHIO_PASSWORD	rachio-mcp-token only	Rachio account password. If unset, rachio-mcp-token prompts interactively with a masked input.

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.

Releasing

Publishing is fully automated via GitHub Actions: tagging a release on GitHub builds the wheel, uploads it to PyPI (via trusted publishing, no API tokens stored), and pushes server.json to the MCP Registry.

Cut a release

1. Locally, before pushing: uv run ruff check and uv run ruff format --check. CI will reject PRs that don't pass.
2. Push the release commit to main.
3. On GitHub, Releases → Draft a new release. Tag: vX.Y.Z (e.g. v0.1.0). The leading v is required; the workflow strips it.
4. Publish release. .github/workflows/publish.yml runs automatically:
   • Rewrites pyproject.toml and server.json to X.Y.Z
   • uv build → dist/*.whl + dist/*.tar.gz
   • Uploads to PyPI via OIDC trusted publishing
   • Uploads server.json to the MCP Registry via GitHub OIDC

One-time setup (before the first release)

1. Create a PyPI pending publisher. Go to pypi.org/manage/account/publishing/ and add a new pending publisher:
   • PyPI Project Name: rachio-mcp
   • Owner: rwestergren
   • Repository: rachio-mcp
   • Workflow: publish.yml
   • Environment: release
2. Create a GitHub Environment. In the repo's Settings → Environments, add an environment named release. Optional: require a reviewer before a release can publish.
3. MCP Registry namespace (io.github.rwestergren/rachio-mcp) is auto-claimed by the first successful mcp-publisher login github-oidc from this repo. No manual registration needed.

License

MIT — see LICENSE.