clousd-mcp

Clousd：为 AI Agent 提供云端真实 Android 手机

每种 Agent 框架都能操控手机，但几乎没有框架能提供一部值得操控的手机。

Clousd 就是这部手机。 每台设备都是一套完整的 Android 系统，基于特定的真实机型打造，从 Pixel、Galaxy 到 Xiaomi，内置 Google Play，并拥有独立的网络出口。用通俗的话告诉它任务，Clousd 的手机 Agent 就会完成操作并给出答复；你也可以逐步自行操控屏幕。应用看到的是手机，而不是模拟器，因此你的 Agent 看到的就是人们实际看到的屏幕。

本仓库是它面向公众的部分：OpenAPI 描述、Python 客户端、MCP 服务，以及供编码 Agent 使用的技能。

两种使用手机的方式

告诉它目标。 POST /v1/runs {"task": "...", "device": "..."}、Python 中的 c.run(...)，以及 MCP 上的 run 工具。Clousd 的 Agent 会查看屏幕、点击和输入，直到达成目标，然后给出答复——附带每一步的回放；按需还可提供符合你所设架构的 JSON。一次调用即可将相同任务交给最多 32 部手机。保存的登录凭据会在手机上输入，你的 Agent 和模型都不会看到它们。

自行操控。 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/）。

编码 Agent 可通过该技能了解工作流：

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 一览表

路由	用途
POST /runs	在 device 或 devices[] 上用自然语言描述任务（最多 32 台设备）：{task, device, credentials:[{package,name}], options:{output_schema, mode, max_steps, timeout}}；使用 Idempotency-Key 请求头
GET /runs、GET /runs/{id}	当前密钥的任务；状态、答案、structured_output，以及等待用户处理的卡片
GET /runs/{id}/events	实时事件（Server-Sent Events）：状态、步骤、计划、卡片、答案、结束
GET /runs/{id}/trajectory、/steps/{n}.jpg	每个步骤及对应屏幕
POST /runs/{id}/answer、/message、/cancel	回答问题或权限请求、与正在运行的 Agent 对话、停止任务
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 的 OpenAPI 3.1 描述（https://api.clousd.com/v1）
python/	clousd：Python 客户端（运行任务、定时任务、登录信息、webhook、设备、观察/操作、重置）；clousd.agent（使用你自己的模型进行逐步操作的循环）；clousd.bench；clousd CLI
mcp/	clousd-mcp：MCP 服务，可本地运行或托管
skills/clousd	编码 Agent 技能：如何操作 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 Agent 的手机：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。