Clousd MCP

Clousd: real Android phones in the cloud, for AI agents

Every agent framework can tap a phone. Almost none has a phone worth tapping.

Clousd is the phone. Each device is a full Android system on the Android version you pick (12 to 17), with Google Play inside and its own network exit. Give it a task in plain words and Clousd's phone agent does the steps and answers; or drive the screen yourself, step by step. Apps see a phone, not an emulator, so your agent sees the screens a person sees.

This repository is the public side of it: the OpenAPI description, the Python client, the MCP server and the skill for coding agents.

Two ways to use a phone

Give it the goal. POST /v1/runs {"task": "...", "device": "..."}, c.run(...) in Python, the run tool over MCP. Clousd's agent looks at the screen, taps and types until the goal is reached, and finishes with an answer - plus a replay of every step, and JSON in your schema when you ask for it. One call gives the same task to up to 32 phones. Saved logins are typed on the phone without your agent or the model seeing them.

Drive it yourself. observe returns a fresh screenshot with a number on every element; act taps an element, types, swipes, opens apps and links, and waits until the screen settles. Snapshots reset a phone to a saved state in seconds.

Quick start

MCP

Hosted, nothing to install: https://api.clousd.com/mcp. Apps with connectors (Claude.ai, ChatGPT…) sign in with OAuth - just add the URL. Other clients send the key in the header:

{

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

Local: pip install clousd-mcp, then {"command": "clousd-mcp", "env": {"CLOUSD_API_KEY": "cl_live_..."}}.

Tools: account, devices, run, run_status, answer, observe, act, credentials, schedules (mcp/).

Coding agents learn the workflow from the skill:

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)

More in python/.

Plain 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 in one table

Keys have a scope (read or read & write) and an explicit list of phones; keys travel only in the Authorization header. Limits: 120 requests a minute per key and device, 600 a minute per key across devices, 60 a minute for everything else; 429 comes with Retry-After. Errors are JSON: {"error": "short_code", "message": "what happened"}. Full description: openapi.yaml; reference: clousd.com/docs/reference.

What is in this repository

Upgrading from 1.5

1.6 adds your apps. An app is an APK you upload once and install by id on any of your phones; there is no catalog of other people's apps (Google Play apps are installed in the Play Store on the phone). GET /v1/apps lists your APKs (id, name, size, package, version), POST /v1/apps uploads one as a file up to 300 MB, POST /v1/apps/{id}/install {devices} installs it, DELETE /v1/apps/{id} removes it from storage. POST /v1/media also takes a multipart file now (photo 25 MB, video 200 MB, document 50 MB, apk 300 MB). Every APK is checked on upload and before each install - a real Android app, 64-bit ARM native code when it has any, not a root or system-modification tool - and refused with 422 apk_rejected and the reason otherwise. SDK: c.apps(), c.upload_app(path), c.install_app(id, devices), c.delete_app(id); c.upload_media(path) sends the file as a file. MCP: the apps tool.

Upgrading from 1.4

1.5 creates phones by Android version only. POST /v1/devices {android: "14"} (versions: GET /v1/android); the phone model is picked by the service. GET /v1/models answers 410, and devices no longer carry a model field. A phone not renamed is called Phone #N. An old body with profile still works and keeps only that model's Android version. Python: c.create_device(android="14"), c.android_versions(); c.models() is deprecated.

Upgrading from 1.2

1.3 adds the Library: GET /v1/media lists the account's files (photos, videos, documents, apks) with ids and folders, POST /v1/media uploads one, POST /v1/media/send copies files to phones. Pass ids to POST /v1/runs as files and they are placed on the phone before the first step (photos and videos in the gallery, documents in Downloads, apks installed). SDK: c.run(task, files=[...]), c.media(), c.upload_media(), c.send_media(); MCP: the library tool and files on run. Creating a device no longer takes plan: phones run pay as you go, a plan's minutes are used first.

Upgrading from 1.1

1.2 removes saved device states. /v1/devices/{name}/snapshots, /profiles and /worlds answer 410; to start from a clean phone call POST /v1/devices/{name}/reset (apps and data are wiped, the Android version stays the same). Python: device.reset() replaces snapshots(), save_snapshot(), restore() and clone().

Upgrading from 0.3

1.0 gives phones goals instead of scripts. /v1/recipes, /v1/groups, /v1/accounts, /v1/texts and the device recipe / record routes answer 410 with where to go instead: tasks are POST /v1/runs, logins are /v1/credentials. MCP: run / run_status / answer / credentials / schedules replace fleet, recipe, resources, network, snapshots and inspect. Keys in the URL are no longer accepted.

Building from this repository

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

Links

• Phones for AI agents: https://clousd.com/agents/
• Docs: https://clousd.com/docs/ · API reference: https://clousd.com/docs/reference/
• Pricing: https://clousd.com/pricing/
• Packages: https://pypi.org/project/clousd/ · https://pypi.org/project/clousd-mcp/
• MCP registry entry: io.github.Clousd-Android/clousd-mcp · hosted endpoint: https://api.clousd.com/mcp

License

MIT. See LICENSE.