rachio-mcp

rachio-mcp

Rachio のスプリンクラーコントローラー向け MCP（Model Context Protocol） サーバーです。リバースエンジニアリングによって解析した Android アプリの gRPC API を利用しています。

公開されている Rachio API では、スケジュールへの読み取り専用アクセスと、いくつかの単一アクション用エンドポイントしか提供されていません。一方、このサーバーは、公式モバイルアプリが使用するものと同じ内部 gRPC バックエンド（cloud.rach.io:443）に接続し、エージェントにすべての操作を提供します。デバイスとゾーンの一覧表示、スケジュールの確認、新しいスケジュールの作成とプレビュー、スケジュールの更新と削除、ゾーンの手動運転の開始と停止、雨天による遅延の設定などが可能です。

⚠️ 非公式です。 このサーバーはリバースエンジニアリングした API を使用しています。Rachio Android v4.21.18 時点で動作しますが、Rachio のサポート対象ではありません。スキーマは予告なく変更される場合があります。

機能

• デバイスとゾーン — コントローラー、センサー、気象観測所を一覧表示します。ゾーンの土壌、ノズル、植物の設定や現在の状態を確認できます
• スケジュール — スケジュールの一覧表示、読み取り、プレビュー（ドライラン）、作成、更新、削除、コピー、実行、スキップができます
• リアルタイム制御 — 散水の停止、指定したゾーンの手動運転、雨天による遅延の設定、現在実行中のゾーンのスキップ／一時停止／再開ができます
• コンテキスト — 今後の運転予定カレンダー、最近／過去の運転履歴、有効なアラート、観測／予報の気象情報を確認できます

クイックスタート

1. uv をインストールする

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

2. 長期間有効なアクセストークンを発行する

MCP サーバーが Rachio のパスワードを受け取ることはありません。代わりに、長期間有効（約25年間）なアクセストークンを一度発行し、そのトークンだけを MCP クライアントに渡します。

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

Rachio のメールアドレスとパスワードの入力を求められた後、MCP クライアントの設定に貼り付ける RACHIO_ACCESS_TOKEN の値が表示されます。このトークンは、パスワードを変更するか、別のデバイスから明示的にログアウトするまで有効です。

または、コマンドを 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	1台のデバイスの詳細情報と現在の状態
list_zones	コントローラーに設定されたゾーンと、農業関連のメタデータ
get_zone	1つのゾーンの詳細情報
get_calendar	指定期間の運転予定とスキップイベント
get_run_history	最近／過去に観測されたゾーン運転のテレメトリーとカレンダー情報
get_active_alerts	デバイスまたはゾーンの未解決アラート
get_weather	場所の観測および予報の気象情報

スケジュールの CRUD

ツール	説明
list_schedules	デバイス、場所、ゾーン、またはスケジュール ID で絞り込みます
get_schedule	1つのスケジュールと、それに関連する場所／デバイス
preview_schedule	ドライラン — create_schedule が作成するスケジュールを、サーバーが生成した人間が読める要約も含めて返します。永続化は行いません
create_schedule	新しいスケジュールを作成します
update_schedule	部分マージによる編集：名前、有効／無効、タイミング／条件、曜日の制限、ゾーンごとの追加／更新／削除
delete_schedule	完全に削除します。取り消せません
copy_schedule	既存のスケジュールを複製します
run_schedule	即時実行を開始します
skip_schedule	次回の予定実行をスキップするか、再設定します
get_schedule_runs	スケジュールの過去の実行とスキップイベント

ライブコントローラー操作

ツール	説明
stop_watering	実行中の処理をすべて停止します
start_zones	ゾーン番号と散水時間を指定して、1つ以上のゾーンを手動で開始します
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 でスケジュールを読み込み、変更するフィールド（名前、有効状態、タイミング／条件、days、または zones／zone_ids_to_remove）だけを渡します。省略したフィールドは変更されません。

動作の仕組み

このサーバーは、Rachio Android アプリが使用するものと同じバックエンドである cloud.rach.io:443 に、TLS で保護された gRPC 経由で接続します。認証には、Android アプリにハードコードされたクライアント認証情報を使用し、oauth.rach.io/oAuth/token に対して OAuth 2 パスワードグラントを実行します。

gRPC の .proto 定義は、jadx を使って Rachio Android APK（v4.21.18）を逆コンパイルし、生成された Java クラスから埋め込みの FileDescriptorProto ペイロードを抽出して、protoc で変換することでクリーンな .proto ソースを生成し、復元しました。23個の MCP ツールで使用する約40個のメッセージ／サービス用のコンパイル済み Python スタブは、src/rachio_mcp/proto/ に同梱されています。

アプリの 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 を読み込み、初回使用時に（LocationService.ListLocations 経由で）ユーザーの user_id を遅延取得し、プロセスの存続期間中はその両方をメモリ内に保持します。ディスクへの書き込みはありません。

環境変数

変数	必須	説明
RACHIO_ACCESS_TOKEN	はい	rachio-mcp-token が生成する長期間有効なベアラートークンです。取り消されない限り、約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 が入力内容を伏せた状態で対話形式の入力を求めます。

RACHIO_EMAIL と RACHIO_PASSWORD は、MCP サーバー自体が読み取ることはありません。これらは初回のトークン生成 CLI に渡すためだけに使用します。

トランスポート

stdio のみです。OAuth 2.1 を使用したリモート HTTP は v0.1 ではサポートされていません。

ライセンス

MIT — LICENSE を参照してください。