> For the complete documentation index, see [llms.txt](https://docs.incogniton.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.incogniton.com/cloud-phones/control-cloud-phones-from-scripts.md).

# Control cloud phones from scripts and AI clients

List, start, stop and connect to cloud phones from your own scripts with the local REST API or the Incogniton CLI, or from an AI client through MCP.

Turn on the local REST API in **Settings > Automation** (switch on **Enable automation API** and click **Save**). Your scripts and the Incogniton CLI can then list your cloud phones, start and stop them, and get an ADB address for them. AI clients connected with an **MCP token** can list, start, stop and create cloud phones.

This page is about controlling phones from outside the app. For the ready-made tasks you run on phones inside Incogniton, see **Phone automation** in [Manage cloud phones](https://docs.incogniton.com/cloud-phones/manage-cloud-phones.md#automation).

### What you need

* The local REST API switched on in **Settings > Automation**. See [Use the local REST API](https://docs.incogniton.com/automation-api-and-sdks/local-rest-api.md). The automation API is a paid feature.
* Incogniton open and logged in on the same computer as your script. The API listens on `127.0.0.1`, port 35000 by default.
* In a team, the right cloud-phone permission: **Use cloud phones (power, restart, connect)** to list, start and stop phones, and **Manage cloud phones (edit, proxy, reset, Android version, ADB, root, apps, automation, move)** to switch ADB on.

### What you can do with the local REST API

| Action                                                                                            | Endpoint                         | CLI command                |
| ------------------------------------------------------------------------------------------------- | -------------------------------- | -------------------------- |
| List your team's cloud phones with their ID, name, group, status, Android version and ADB address | `GET /cloudphone/list`           | `cloudphone-list`          |
| Start phones without opening their screen (for ADB, apps and automation)                          | `POST /cloudphone/start`         | `cloudphone-start`         |
| Start phones and open each one's screen in a window in Incogniton                                 | `POST /cloudphone/start-display` | `cloudphone-start-display` |
| Power phones off                                                                                  | `POST /cloudphone/stop`          | `cloudphone-stop`          |
| Enable ADB on a running phone and get its local address                                           | `POST /cloudphone/adb`           | `cloudphone-adb`           |

Start and stop take a list of 1 to 100 phone IDs from the phone list. Each phone is checked on its own (minutes left, subscription active, proxy set, not resetting), so some phones can start while others are refused; the answer gives the reason per phone.

A phone started this way keeps running, and using minutes, until you stop it. Stopping a phone also closes its window and its local ADB connection in Incogniton.

The ADB action returns a local address such as `127.0.0.1:6555`. Connect to it with `adb connect`, exactly like the address from **Copy ADB command** in the app. The phone must be running. See [Connect to a cloud phone with ADB](https://docs.incogniton.com/cloud-phones/connect-to-a-cloud-phone-with-adb.md).

You can't edit, restart or reset a cloud phone through the local REST API. Do that in the app: see [Edit, restart or reset a cloud phone](https://docs.incogniton.com/cloud-phones/edit-restart-and-reset-cloud-phones.md).

### Use the Incogniton CLI

Every action above has a matching CLI command. Click **Download CLI** on the **Automation** tab to install it; while it is installed, it updates itself when the app starts. Run `incogniton-cli cloudphone-list` to see your phones and their IDs. See the [CLI documentation](https://api-docs.incogniton.com/cli) for how commands, flags and output work.

### Control cloud phones from an AI client (MCP)

When you connect an AI client such as Claude or Cursor with an MCP token (**Settings > Automation > Generate MCP Token**, see [Connect AI clients with MCP](https://docs.incogniton.com/automation-api-and-sdks/connect-ai-clients-mcp.md)), the AI client can:

* **List** your cloud phones with their status and whether ADB is on.
* **Start** phones without a screen, for ADB, installed apps and automation.
* **Stop** phones.
* **Create** a new cloud phone with a proxy from your Proxy Library.

The MCP tools run on Incogniton's servers, so they also work when the Incogniton app is closed. They can't open a phone's screen: to see a phone, open it in the app (**Cloud Phones**, then **Power on** or **Connect**). A phone started through MCP keeps running until it is stopped, or until your Incogniton app closes while **Stop my cloud phones when Incogniton closes** is on (phones running an automation task keep running).

{% hint style="info" %}
The developer documentation at [api-docs.incogniton.com](https://api-docs.incogniton.com/apis) covers the profile, cookie and automation endpoints. If you have questions about automating cloud phones, contact our [support department](https://incogniton.com/contact/).
{% endhint %}
