English Français العربية

io.github.Clousd-Android/clousd-mcp

Registre officiel Productivité

Real Android phones in the cloud for AI agents: give phones a task in plain words and get the answer

Code source Site web Documentation

Installation

Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).

Remote (streamable-http)
Claude Code 
claude mcp add --transport http clousd-mcp 'https://api.clousd.com/mcp' --header 'Authorization: <Bearer cl_live_... (Clousd API key; apps with connectors sign in with OAuth instead)>'
Configuration JSON (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "clousd-mcp": {
            "type": "http",
            "url": "https://api.clousd.com/mcp",
            "headers": {
                "Authorization": "<Bearer cl_live_... (Clousd API key; apps with connectors sign in with OAuth instead)>"
            }
        }
    }
}
PYPI package clousd-mcp
Claude Code 
claude mcp add clousd-mcp -e 'CLOUSD_API_KEY=<your clousd_api_key>' -- uvx clousd-mcp==1.2.0
Configuration JSON (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "clousd-mcp": {
            "command": "uvx",
            "args": [
                "clousd-mcp==1.2.0"
            ],
            "env": {
                "CLOUSD_API_KEY": "<your clousd_api_key>"
            }
        }
    }
}

Variables d'environnement

  • CLOUSD_API_KEY obligatoire secret Clousd API key (cl_live_...) from the dashboard, Settings -> Connections -> API keys

Documentation

Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.

Sommaire
  1. Clousd: real Android phones in the cloud, for AI agents
  2. Two ways to use a phone
  3. Quick start
  4. API in one table
  5. What is in this repository
  6. Upgrading from 1.1
  7. Upgrading from 0.3
  8. Building from this repository
  9. Links
  10. License

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 built as a specific real model, Pixel to Galaxy to Xiaomi, 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

RoutePurpose
POST /runsa task in plain words on device or devices[] (up to 32): {task, device, credentials:[{package,name}], options:{output_schema, mode, max_steps, timeout}}; Idempotency-Key header
GET /runs, GET /runs/{id}runs of the key; status, answer, structured_output, the card it waits on
GET /runs/{id}/eventslive events (Server-Sent Events): status, step, plan, card, answer, end
GET /runs/{id}/trajectory, /steps/{n}.jpgevery step with its screen
POST /runs/{id}/answer, /message, /cancelanswer a question or permission, talk to the running agent, stop it
GET/POST /schedules, POST /schedules/{id}/toggle, /deletetasks at a time on days of the week
GET/POST /credentials, POST /credentials/{id}/fields, DELETE …saved logins; values are never returned
GET/POST /webhooks, …/{id}/rotate, /toggle, /test, GET …/deliveriesevents to your server, signed with your secret
GET /devices, GET /devices/{name}, POST /devices, start/stop/restart/resetphones of the key and their lifecycle; reset wipes apps and data
GET /devices/{name}/observe, POST /devices/{name}/act, /screenshot, /screenrecordthe screen, step by step
GET/POST /devices/{name}/network, GET/POST /proxiesthe phone's network exit
GET/POST/DELETE /devices/{name}/adbADB over a relay: one-time code, IP allow-list, expiry
GET /balanceplan, phones, money left and warnings to show the user

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

PartWhat it is
openapi.yamlOpenAPI 3.1 description of the public API v1 (https://api.clousd.com/v1)
python/clousd: Python client (runs, schedules, logins, webhooks, devices, observe/act, reset), clousd.agent (a step-by-step loop on your own model), clousd.bench, the clousd CLI
mcp/clousd-mcp: the MCP server, local or hosted
skills/clousdskill for coding agents: how to work with Clousd phones
docs/agent-loop.mddriving a phone yourself: the observe → act → verify loop
server.json, smithery.yamlregistry metadata

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 model and Android stay 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

License

MIT. See LICENSE.

Questions fréquentes

Qu'est-ce que io.github.Clousd-Android/clousd-mcp ?

Real Android phones in the cloud for AI agents: give phones a task in plain words and get the answer

Comment installer io.github.Clousd-Android/clousd-mcp ?

Il fonctionne comme serveur distant. Dans Claude Code : claude mcp add --transport http clousd-mcp 'https://api.clousd.com/mcp' --header 'Authorization: <Bearer cl_live_... (Clousd API key; apps with connectors sign in with OAuth instead)>'. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.

Faut-il une clé API pour io.github.Clousd-Android/clousd-mcp ?

Oui. Il attend CLOUSD_API_KEY, Authorization, à renseigner dans sa configuration.

io.github.Clousd-Android/clousd-mcp est-il open source ?

Oui. Son code est sur GitHub sous licence MIT.

Qui maintient io.github.Clousd-Android/clousd-mcp ?

Il est publié par Clousd-Android. AI.tn le référence sans le maintenir ni le recommander.

Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.