io.github.rwestergren/rachio-mcp
MCP server for Rachio sprinkler controllers β schedules, zones, and live watering control
Ask AI about io.github.rwestergren/rachio-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.rwestergren/rachio-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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):
RACHIO_EMAIL=you@example.com 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
list_devicesβ pick your controllerlist_zones(device_id=...)β note each zone's id andzone_numberlist_schedules(device_id=...)andget_schedule(schedule_id=...)β understand what's already configuredpreview_schedule(...)β dry-run your proposed schedule. Read the returnedsummarystring and the per-zone breakdowncreate_schedule(...)(same arguments) β commitget_schedule(schedule_id=<new>)β confirmdelete_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.
License
MIT β see LICENSE.
