rachio-mcp

rachio-mcp

一个适用于 Rachio 喷灌控制器的 MCP（Model Context Protocol） 服务，基于逆向工程分析得出的 Android 应用 gRPC API 构建。

Rachio 公共 API 仅提供日程的只读访问权限，以及少数单一操作端点。本服务则直接连接官方移动应用使用的同一内部 gRPC 后端（cloud.rach.io:443），为 Agent 提供完整的操作集：列出设备和区域、检查日程、创建并预览新日程、更新和删除日程、启动和停止区域手动运行、设置雨天延迟等。

⚠️ 非官方。 本服务使用逆向工程分析得出的 API。截至 Rachio Android v4.21.18，该服务可以正常运行，但不受 Rachio 支持。API 架构可能随时变更，恕不另行通知。

功能

• 设备和区域 — 列出控制器、传感器和气象站；检查区域的土壤、喷头和植物配置，以及实时状态
• 日程 — 列出、读取、预览（试运行）、创建、更新、删除、复制、运行和跳过日程
• 实时控制 — 停止浇水、手动运行指定区域、设置雨天延迟、跳过／暂停／恢复当前正在运行的区域
• 上下文 — 即将运行的日历、近期／过往运行历史记录、有效警报、观测／预报天气读数

快速开始

1. 安装 uv

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

2. 获取长期有效的访问令牌

MCP 服务本身不会获取你的 Rachio 密码。你只需获取一次长期有效（约 25 年）的访问令牌，并将令牌提供给 MCP 客户端。

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

系统会提示你输入 Rachio 电子邮箱和密码，然后输出一个 RACHIO_ACCESS_TOKEN 值，供你粘贴到 MCP 客户端配置中。除非你更改密码或主动从其他设备登出，否则令牌会一直有效。

或者，如果你希望这些命令永久添加到 PATH 中，可以安装一次：

uv tool install rachio-mcp

之后，rachio-mcp-token（以及 rachio-mcp 本身）就可以作为常规命令使用。

用于脚本（例如通过管道传入密码管理器）：

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

3. 配置 MCP 客户端

uvx 会按需下载并运行服务，无需单独安装。

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"
      }
    }
  }
}

如果之后调用工具时返回“token rejected”错误，请重新运行 rachio-mcp-token 获取新令牌，并更新配置。

可用工具

通过 stdio 传输提供 24 个工具。

发现

工具	描述
list_devices	账户中的所有设备——控制器、传感器、气象站
get_device	单个设备的完整详情和实时状态
list_zones	控制器上配置的区域，以及农艺元数据
get_zone	单个区域的完整详情
get_calendar	指定日期范围内的计划运行和跳过事件
get_run_history	近期／过往区域运行的观测遥测数据，以及日历上下文
get_active_alerts	设备或区域上尚未解决的警报
get_weather	某个位置的观测和预报天气读数

日程增删改查

工具	描述
list_schedules	按设备、位置、区域或日程 ID 筛选
get_schedule	单个日程及其位置／设备
preview_schedule	试运行——返回 create_schedule 将会生成的日程，包括服务端生成的易读摘要。不会保存
create_schedule	创建新日程
update_schedule	部分合并编辑：名称、启用状态、时间／条件、日期限制，以及添加／更新／移除各区域
delete_schedule	永久删除，具有破坏性
copy_schedule	复制现有日程
run_schedule	立即触发运行
skip_schedule	跳过或重新启用下一次计划运行
get_schedule_runs	某个日程的过往运行和跳过事件

实时控制器操作

工具	描述
stop_watering	停止当前正在运行的任何操作
start_zones	按区域编号和时长手动启动一个或多个区域
set_rain_delay	将所有计划推迟到指定时间
skip_current_zone	跳到当前运行中的下一个区域
pause_watering	将当前区域暂停 N 秒
resume_watering	恢复已暂停的运行

所有 device_id、zone_id、schedule_id 和 location_id 参数都是通过 list_* 工具获取的 UUID。日期使用 YYYY-MM-DD（年度重复计划使用 MM-DD）；时间使用 HH:MM。

更改计划的推荐工作流

1. list_devices → 选择你的控制器
2. list_zones(device_id=...) → 记下每个区域的 ID 和 zone_number
3. list_schedules(device_id=...) 和 get_schedule(schedule_id=...) → 了解当前已配置的内容
4. preview_schedule(...) → 对拟定的计划进行试运行。查看返回的 summary 字符串和各区域的细分信息
5. create_schedule(...)（使用相同参数）→ 提交
6. get_schedule(schedule_id=<new>) → 确认
7. delete_schedule(schedule_id=<new>) → 如有需要则回滚

可以反复安全地调用 preview_schedule——它绝不会写入任何内容。

如需编辑现有计划，而不是重新创建，请使用 update_schedule。它会执行部分合并：先用 get_schedule 读取计划，然后只传入要更改的字段（name、enabled、timing/criteria、days 或 zones/zone_ids_to_remove）。未提供的字段将保持不变。

工作原理

此服务通过受 TLS 保护的 gRPC 与 cloud.rach.io:443 通信，使用的后端与 Rachio Android 应用相同。身份验证通过 oauth.rach.io/oAuth/token 使用 OAuth 2 密码授权，并采用 Android 应用中硬编码的客户端凭据。

gRPC .proto 定义通过 jadx 对 Rachio Android APK（v4.21.18）进行反编译后恢复：从生成的 Java 类中提取嵌入的 FileDescriptorProto 负载，再通过 protoc 转换为规范的 .proto 源文件。src/rachio_mcp/proto/ 中附带了 23 个 MCP 工具所用的约 40 个消息和服务的预编译 Python 存根。

每当应用的 proto 接口发生变化时，都要重新生成这些存根：

scripts/build_protos.sh

存根生成器从 reverse-engineering/protos/ 读取文件；该目录不会打包进 wheel，但会与源代码一同保留，以便将来更新。

Python API

MCP 服务封装了一个独立客户端，可直接使用：

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"])

客户端从环境中读取 RACHIO_ACCESS_TOKEN，并在首次使用时延迟获取用户的 user_id（通过 LocationService.ListLocations），然后在进程的整个生命周期内将两者保存在内存中。不会向磁盘写入任何内容。

环境

变量	必需	描述
RACHIO_ACCESS_TOKEN	是	由 rachio-mcp-token 生成的长期有效 Bearer 令牌。除非撤销，否则有效期约为 25 年。
LOG_LEVEL	否	Python 日志级别（默认值：INFO）。日志输出到 stderr；stdio 传输的 stdout 专用于 MCP 协议。

生成令牌（一次性设置）

变量	使用方	描述
RACHIO_EMAIL	仅供 rachio-mcp-token 使用	Rachio 账户邮箱。若未设置，rachio-mcp-token 会以交互方式提示输入。
RACHIO_PASSWORD	仅供 rachio-mcp-token 使用	Rachio 账户密码。若未设置，rachio-mcp-token 会以交互方式提示输入，并在输入时隐藏内容。

MCP 服务本身绝不会读取 RACHIO_EMAIL 或 RACHIO_PASSWORD——它们仅用于向一次性令牌生成命令行工具提供信息。

传输

仅支持 stdio。v0.1 不支持使用 OAuth 2.1 的远程 HTTP。

许可证

MIT——参见 LICENSE。