clousd-mcp

Clousd：AI エージェントのための、クラウド上の実機 Android スマートフォン

どのエージェントフレームワークもスマートフォンを操作できます。しかし、操作する価値のあるスマートフォンを備えているものは、ほとんどありません。

Clousd はスマートフォンそのものです。 各デバイスは、Pixel から Galaxy、Xiaomi まで、特定の実機モデルとして構築された完全な Android システムです。Google Play が内蔵され、独自のネットワーク出口を備えています。平易な言葉でタスクを与えると、Clousd のスマートフォンエージェントが手順を実行して回答します。または、画面を自分で一つずつ操作することもできます。アプリからはエミュレーターではなくスマートフォンに見えるため、エージェントには人が見るのと同じ画面が表示されます。

このリポジトリはその公開部分で、OpenAPI の記述、Python クライアント、MCP サーバー、コーディングエージェント向けのスキルを含みます。

スマートフォンを使う 2 つの方法

目標を与える。 POST /v1/runs {"task": "...", "device": "..."}、Python では c.run(...)、MCP では run ツールを使います。Clousd のエージェントは画面を確認し、目標を達成するまでタップや入力を続けて、回答を返します。さらに、すべての手順の再生と、指定した場合はスキーマに沿った JSON も返します。1 回の呼び出しで、最大 32 台のスマートフォンに同じタスクを実行させられます。保存済みのログイン情報はスマートフォン上で入力されるため、エージェントにもモデルにも見られません。

自分で操作する。 observe は、各要素に番号が付いた最新のスクリーンショットを返します。act では、要素のタップ、入力、スワイプ、アプリやリンクの起動、画面が落ち着くまでの待機ができます。スナップショットを使えば、保存した状態にスマートフォンを数秒で戻せます。

クイックスタート

MCP

ホスト型なので、インストールは不要です：https://api.clousd.com/mcp。コネクター対応アプリ（Claude.ai、ChatGPT など）では、OAuth でサインインし、URL を追加するだけです。その他のクライアントでは、キーをヘッダーで送信します。

{
  "mcpServers": {
    "clousd": { "url": "https://api.clousd.com/mcp", "headers": { "Authorization": "Bearer cl_live_..." } }
  }
}

ローカルで使う場合は、pip install clousd-mcp を実行し、続いて {"command": "clousd-mcp", "env": {"CLOUSD_API_KEY": "cl_live_..."}} を設定します。

ツール：account、devices、run、run_status、answer、observe、act、credentials、schedules（mcp/）。

コーディングエージェントは、スキルからワークフローを学習します。

npx skills add https://github.com/Clousd-Android/clousd-sdk --skill clousd

Python

pip install clousd
export CLOUSD_API_KEY=cl_live_...

from clousd import Clousd

c = Clousd()
run = c.run("Open Settings and tell me the Android version", device="dev_04f2", wait=True)
print(run.status, run.answer)                     # completed  Android 15

phone = c.device("dev_04f2")                      # or step by step
phone.open_app("com.android.chrome")
phone.tap_text("Search")
phone.type("weather in Berlin")
phone.key("enter")
phone.wait_text("Berlin", timeout=30)

詳しくは python/ をご覧ください。

プレーン HTTPS

curl -H "Authorization: Bearer cl_live_..." https://api.clousd.com/v1/devices
curl -H "Authorization: Bearer cl_live_..." -H "Content-Type: application/json" \
     -d '{"task":"Open Settings and tell me the Android version","device":"dev_04f2"}' https://api.clousd.com/v1/runs
curl -N -H "Authorization: Bearer cl_live_..." https://api.clousd.com/v1/runs/r_8f2c/events      # live steps (SSE)
curl -H "Authorization: Bearer cl_live_..." "https://api.clousd.com/v1/devices/dev_04f2/observe?w=540"

API を 1 つの表にまとめました

ルート	用途
POST /runs	device または devices[]（最大 32 台）で、平易な言葉でタスクを指定します：{task, device, credentials:[{package,name}], options:{output_schema, mode, max_steps, timeout}}。Idempotency-Key ヘッダー
GET /runs、GET /runs/{id}	キーの実行一覧。ステータス、回答、構造化出力、回答を待っているカード
GET /runs/{id}/events	ライブイベント（Server-Sent Events）：ステータス、ステップ、プラン、カード、回答、終了
GET /runs/{id}/trajectory、/steps/{n}.jpg	画面付きの全ステップ
POST /runs/{id}/answer、/message、/cancel	質問や権限確認に回答する、実行中のエージェントとやり取りする、停止する
GET/POST /schedules、POST /schedules/{id}/toggle、/delete	曜日の指定時刻に実行するタスク
GET/POST /credentials、POST /credentials/{id}/fields、DELETE …	保存済みのログイン情報。値が返されることはありません
GET/POST /webhooks、…/{id}/rotate、/toggle、/test、GET …/deliveries	シークレットで署名された、サーバーへのイベント
GET /devices、GET /devices/{name}、POST /devices、start/stop/restart/reset	キーに紐づくスマートフォンとそのライフサイクル。reset はアプリとデータを消去します
GET /devices/{name}/observe、POST /devices/{name}/act、/screenshot、/screenrecord	画面をステップごとに操作します
GET/POST /devices/{name}/network、GET/POST /proxies	スマートフォンのネットワーク出口
GET/POST/DELETE /devices/{name}/adb	リレー経由の ADB：ワンタイムコード、IP 許可リスト、有効期限
GET /balance	プラン、スマートフォン、残高、ユーザーに表示する警告

キーにはスコープ（read または read & write）と明示的なスマートフォン一覧が設定されます。キーは Authorization ヘッダーでのみ送信してください。制限：キーおよびデバイスごとに毎分 120 リクエスト、デバイス横断でキーごとに毎分 600 リクエスト、その他すべては毎分 60 リクエストです。429 には Retry-After が付属します。エラーは JSON 形式です：{"error": "short_code", "message": "what happened"}。 詳細な説明：openapi.yaml。リファレンス：clousd.com/docs/reference。

このリポジトリの内容

部分	内容
openapi.yaml	公開 API v1（https://api.clousd.com/v1）の OpenAPI 3.1 定義
python/	clousd：Python クライアント（実行、スケジュール、ログイン情報、ウェブフック、デバイス、監視／操作、リセット）、clousd.agent（独自のモデルで実行するステップごとのループ）、clousd.bench、clousd CLI
mcp/	clousd-mcp：ローカルまたはホスト型の MCP サーバー
skills/clousd	コーディングエージェント向けスキル：Clousd のスマートフォンの操作方法
docs/agent-loop.md	自分でスマートフォンを操作する方法：監視 → 操作 → 検証のループ
server.json、smithery.yaml	レジストリのメタデータ

1.1 からのアップグレード

1.2 では、保存済みのデバイス状態が削除されます。/v1/devices/{name}/snapshots、/profiles、/worlds は 410 を返します。スマートフォンを初期状態に戻すには POST /v1/devices/{name}/reset を呼び出してください（アプリとデータは消去されますが、モデルと Android はそのままです）。Python では、device.reset() が snapshots()、save_snapshot()、restore()、clone() に置き換わります。

0.3 からのアップグレード

1.0 では、スマートフォンにスクリプトではなく目標を指定します。/v1/recipes、/v1/groups、/v1/accounts、/v1/texts と、デバイスの recipe／record ルートは、移行先を示す 410 を返します。タスクには POST /v1/runs、ログイン情報には /v1/credentials を使います。MCP では、run／run_status／answer／credentials／schedules が、fleet、recipe、resources、network、snapshots、inspect に置き換わります。URL 内のキーは使用できなくなりました。

このリポジトリからビルドする

pip install -e python
pip install -e mcp
python -m unittest discover -s python/tests     # offline: a fake server and a scripted model, no key needed

リンク

• AI エージェント向けのスマートフォン：https://clousd.com/agents/
• ドキュメント：https://clousd.com/docs/ · API リファレンス：https://clousd.com/docs/reference/
• デバイスカタログ（実機モデル150種類以上、Android 12～17）：https://clousd.com/devices/
• 料金：https://clousd.com/pricing/
• パッケージ：https://pypi.org/project/clousd/ · https://pypi.org/project/clousd-mcp/
• MCP レジストリエントリー：io.github.Clousd-Android/clousd-mcp · ホスト型エンドポイント：https://api.clousd.com/mcp

ライセンス

MIT。詳細はLICENSEをご覧ください。