<p align="center">
  <img src="assets/logo.svg" width="128" alt="rachio-mcp logo">
</p>

<h1 align="center">rachio-mcp</h1>

<p align="center">
  An <a href="https://modelcontextprotocol.io">MCP</a> server for
  <b>Rachio</b> smart sprinkler controllers, via the official public cloud API.
</p>

---

## What it does

Exposes your Rachio irrigation system to any MCP client (Claude Code, Claude Desktop,
etc.) so you can ask *"is anything watering right now?"*, *"run the front lawn for 10
minutes"*, or *"put it on a 2-day rain delay"* in natural language.

Uses the [Rachio public API](https://rachio.readme.io) — cloud, token-based, works from
anywhere (no need to be on the same network as the controller).

## Tools

| Tool | Purpose |
| --- | --- |
| `list_devices` | all controllers on the account, with status and zone summary |
| `get_status` | one-shot: online, on/paused, rain sensor & delay, what's watering now |
| `list_zones` | zones on a controller (number, name, enabled) |
| `list_schedules` | stored schedule rules (watering times) |
| `start_zone` | run one zone for N minutes (max 180) |
| `start_zones` | run several zones in sequence |
| `stop_watering` | stop everything now |
| `set_rain_delay` | set/clear a rain delay (0–7 days) |
| `run_schedule` | start a stored schedule rule by name or id |
| `set_device_power` | take the controller out of / into standby |

Zones and devices can be referenced by **name or number**, not just their API ids.

## Requirements

- Python 3.12+
- [`uv`](https://docs.astral.sh/uv/)
- A Rachio account and an **API token**

## Get your API token

In the **Rachio mobile app**: `Profile` → `Get API Key` → `Copy`.
It's a single bearer token tied to your account — treat it like a password.

## Install

```bash
git clone https://github.com/rudy325/rachio-mcp.git
cd rachio-mcp
uv sync
```

## Configure

```bash
export RACHIO_API_TOKEN=your-api-token
```

See [`.env.example`](.env.example).

## Register with Claude Code

```bash
claude mcp add rachio \
  --env RACHIO_API_TOKEN=your-api-token \
  -- uv --directory /path/to/rachio-mcp run server.py
```

Or with Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rachio": {
      "command": "uv",
      "args": ["--directory", "/path/to/rachio-mcp", "run", "server.py"],
      "env": { "RACHIO_API_TOKEN": "your-api-token" }
    }
  }
}
```

## Use with other clients (OpenAI, local models, etc.)

This is a standard [MCP](https://modelcontextprotocol.io) server — it speaks the open
protocol over stdio and doesn't care which model or client drives it. Anything that
supports MCP works:

- **OpenAI** — the [Agents SDK](https://openai.github.io/openai-agents-python/mcp/) and
  Responses API accept MCP servers. Point them at:
  `command: "uv"`, `args: ["--directory", "/path/to/rachio-mcp", "run", "server.py"]`,
  with `RACHIO_API_TOKEN` in the environment.
- **Local / open-source models** — via any MCP-capable client (Cline, Continue,
  LibreChat, Open WebUI, Goose, Zed, Cursor) running Ollama, Llama, Qwen, etc.
- **Any other MCP client** — same stdio command as the Claude examples above.

The only requirement is a model that's competent at tool/function calling; the large
hosted models and stronger local ones (Llama 3.1+, Qwen 2.5+) handle it well.

## Notes

- **Multiple controllers:** every tool takes an optional `device` argument (name or id),
  required only when the account has more than one controller.
- **Durations:** zone runs are capped at 180 minutes and rain delays at 7 days, matching
  the API limits.
- **Standby:** `set_device_power(on=false)` puts the controller in standby, pausing all
  scheduled watering until turned back on.
- **Rate limits:** the Rachio API allows 1700 calls/day per token; these tools are all
  single calls, so normal use is nowhere near the limit.

## How it fits together

```
MCP client ──stdio──> server.py ──HTTPS──> api.rach.io/1 ──> your Rachio controller
```

## License

[MIT](LICENSE). Not affiliated with or endorsed by Rachio, Inc.
"Rachio" is a trademark of Rachio, Inc.