Phonebox

Official13 tools

by combined-ai

Cloud Android phones for AI agents: create a phone, read the screen, tap, type, install APKs, park.

This MCP server provides access to “Cloud Android phones for AI agents.” It supports creating a phone instance, reading the screen, and interacting with the device by tapping and typing. It also enables installing APKs and parking the device for later use.

🛠️ Key Features

Create a phone
Read the screen
Tap
Type
Install APKs
Park

🚀 Use Cases

Automated Android UI interaction for AI agents
Screen-based workflows (read screen → act via tap/type)
Deploying Android apps via APK installation

⚡ Developer Benefits

Direct device control actions for agent-driven flows
End-to-end interaction primitives (screen reading and input)

Topics

ai-agentsandroidandroid-automationandroid-mcpclaude-codecloud-phonecodexcursormcpmcp-servermodel-context-protocolphonebox

Captured live from the server via tools/list.

list_phones

List this project's phones, newest first, with their status and when each parks: up to 50 a page, and next_cursor for the next page. Parked phones keep their apps and sign-ins and cost nothing.

Parameters2

status	string	optional	List only the phones in this status. Without it, failed and deleted phones are left out: ask for failed to list those.
cursor	string	optional	next_cursor from the page before, to read the next page.

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "description": "List only the phones in this status. Without it, failed and deleted phones are left out: ask for failed to list those.",
      "type": "string",
      "enum": [
        "creating",
        "starting",
        "ready",
        "parking",
        "parked",
        "unavailable",
        "failed",
        "deleted"
      ]
    },
    "cursor": {
      "description": "next_cursor from the page before, to read the next page.",
      "type": "string",
      "maxLength": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

create_phone

Create a cloud Android phone and wait until it is ready (usually under two minutes). It costs $0.06 a minute while running. Always park it when you're done. If it is still creating or starting when this returns, call get_phone with its ID and wait "ready" to keep waiting: it only reads, while start_phone would renew the session.

Parameters6

name	string	optional	A name to tell the phone apart, up to 80 characters. The default is its ID.
country	string	optional	Where the phone appears to be: one of the listed two-letter ISO 3166-1 country codes, such as US or DE. Any other code is refused before a phone is made. Leave it out for any country.
metadata	object	optional	Up to 20 string pairs of your own, such as a customer ID. Keys have up to 40 characters and values up to 256.
idle_timeout	integer	optional	Seconds after the phone's last activity, its last_active_at, at which it parks itself, from 60 to 3600. Calls move last_active_at at most once every 15 seconds. The default is 300.
max_duration	integer	optional	The most seconds this session may run before the phone parks, from 60 to 10800. The default is up to 900, shortened automatically to available credit and the spending limit.
idempotency_key	string	optional	A unique key for this phone. If a call times out, repeat it with the same key and settings to get the same phone instead of a second one. If that phone has failed, create the next one with a new key.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "description": "A name to tell the phone apart, up to 80 characters. The default is its ID.",
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "country": {
      "description": "Where the phone appears to be: one of the listed two-letter ISO 3166-1 country codes, such as US or DE. Any other code is refused before a phone is made. Leave it out for any country.",
      "type": "string",
      "enum": [
        "AR",
        "AU",
        "AT",
        "BE",
        "BR",
        "CA",
        "CL",
        "CO",
        "CZ",
        "DK",
        "EG",
        "FI",
        "FR",
        "DE",
        "GR",
        "HK",
        "IN",
        "ID",
        "IE",
        "IL",
        "IT",
        "JP",
        "KE",
        "MY",
        "MX",
        "NL",
        "NZ",
        "NG",
        "NO",
        "PH",
        "PL",
        "PT",
        "RO",
        "SA",
        "SG",
        "ZA",
        "KR",
        "ES",
        "SE",
        "CH",
        "TW",
        "TH",
        "TR",
        "UA",
        "AE",
        "GB",
        "US",
        "VN"
      ]
    },
    "metadata": {
      "description": "Up to 20 string pairs of your own, such as a customer ID. Keys have up to 40 characters and values up to 256.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 40,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 256
      }
    },
    "idle_timeout": {
      "description": "Seconds after the phone's last activity, its last_active_at, at which it parks itself, from 60 to 3600. Calls move last_active_at at most once every 15 seconds. The default is 300.",
      "type": "integer",
      "minimum": 60,
      "maximum": 3600
    },
    "max_duration": {
      "description": "The most seconds this session may run before the phone parks, from 60 to 10800. The default is up to 900, shortened automatically to available credit and the spending limit.",
      "type": "integer",
      "minimum": 60,
      "maximum": 10800
    },
    "idempotency_key": {
      "description": "A unique key for this phone. If a call times out, repeat it with the same key and settings to get the same phone instead of a second one. If that phone has failed, create the next one with a new key.",
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{7,127}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

get_phone

Read one phone: its status, session and when it parks. With wait, wait until it is ready or parked. It never starts, renews or bills anything, so it is the way to wait for a phone that is still creating or starting.

Parameters2

phone_id	string	required	Phone ID from create_phone or list_phones.
wait	string	optional	"ready" or "parked": wait until the phone gets there. Leave it out to read the phone as it is.

Raw schema

{
  "type": "object",
  "properties": {
    "phone_id": {
      "type": "string",
      "pattern": "^ph_[a-z2-7]{12}$",
      "description": "Phone ID from create_phone or list_phones."
    },
    "wait": {
      "description": "\"ready\" or \"parked\": wait until the phone gets there. Leave it out to read the phone as it is.",
      "type": "string",
      "enum": [
        "ready",
        "parked"
      ]
    }
  },
  "required": [
    "phone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

start_phone

Start a parked phone and wait until it is ready. Its apps, files and sign-ins are kept. On a phone that is already running, it renews the session: a new deadline, with credit reserved for it. If it is still creating or starting when this returns, call get_phone with its ID and wait "ready" to keep waiting: it only reads, while start_phone would renew the session.

Parameters3

idle_timeout	integer	optional	Seconds after the phone's last activity, its last_active_at, at which it parks itself, from 60 to 3600. Calls move last_active_at at most once every 15 seconds. Leave it out to keep the phone's current setting.
max_duration	integer	optional	The most seconds this session may run before the phone parks, from 60 to 10800. Leave it out to keep the phone's current setting.
phone_id	string	required	Phone ID from create_phone or list_phones.

Raw schema

{
  "type": "object",
  "properties": {
    "idle_timeout": {
      "description": "Seconds after the phone's last activity, its last_active_at, at which it parks itself, from 60 to 3600. Calls move last_active_at at most once every 15 seconds. Leave it out to keep the phone's current setting.",
      "type": "integer",
      "minimum": 60,
      "maximum": 3600
    },
    "max_duration": {
      "description": "The most seconds this session may run before the phone parks, from 60 to 10800. Leave it out to keep the phone's current setting.",
      "type": "integer",
      "minimum": 60,
      "maximum": 10800
    },
    "phone_id": {
      "type": "string",
      "pattern": "^ph_[a-z2-7]{12}$",
      "description": "Phone ID from create_phone or list_phones."
    }
  },
  "required": [
    "phone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

park_phone

Park a phone to stop billing. Do this whenever you're done.

Parameters1

phone_id

string

required

Phone ID from create_phone or list_phones.

Raw schema

{
  "type": "object",
  "properties": {
    "phone_id": {
      "type": "string",
      "pattern": "^ph_[a-z2-7]{12}$",
      "description": "Phone ID from create_phone or list_phones."
    }
  },
  "required": [
    "phone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

observe

Read the screen: every visible element with a ref number, text and center, plus a screenshot when asked. Tap elements by ref with the act tool.

Parameters2

phone_id	string	required	Phone ID from create_phone or list_phones.
screenshot	boolean	optional	Whether to include a screenshot, 720 pixels wide. The default is true.

Raw schema

{
  "type": "object",
  "properties": {
    "phone_id": {
      "type": "string",
      "pattern": "^ph_[a-z2-7]{12}$",
      "description": "Phone ID from create_phone or list_phones."
    },
    "screenshot": {
      "default": true,
      "description": "Whether to include a screenshot, 720 pixels wide. The default is true.",
      "type": "boolean"
    }
  },
  "required": [
    "phone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

act

Run up to 20 actions in order (tap, type, key, swipe, scroll, back, home, open_app, open_url, wait_for, …). The batch stops at the first failure, and the result shows the screen where it stopped, unless the screen couldn't be read, or not in time. Never repeat an action whose outcome is unknown; observe first.

Parameters3

phone_id	string	required	Phone ID from create_phone or list_phones.
actions	array	required	From 1 to 20 actions, run in order. Durations are in milliseconds, and the waits in one batch may add up to 60 seconds. Coordinates are device pixels.
observe	string	optional	What the result shows of the screen afterwards: ui (the element list, the default), screenshot, both, or none. A batch that stops early shows the element list, unless the screen couldn't be read, or not in time.

Raw schema

{
  "type": "object",
  "properties": {
    "phone_id": {
      "type": "string",
      "pattern": "^ph_[a-z2-7]{12}$",
      "description": "Phone ID from create_phone or list_phones."
    },
    "actions": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "tap"
              },
              "target": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "x": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000
                      },
                      "y": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000
                      }
                    },
                    "required": [
                      "x",
                      "y"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "ref": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 1000
                      },
                      "snapshot_id": {
                        "type": "string",
                        "pattern": "^snp_[a-z2-7]{12}$"
                      }
                    },
                    "required": [
                      "ref",
                      "snapshot_id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      },
                      "nth": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 50
                      }
                    },
                    "required": [
                      "text"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 300
                      }
                    },
                    "required": [
                      "id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "desc": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      }
                    },
                    "required": [
                      "desc"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            },
            "required": [
              "type",
              "target"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "double_tap"
              },
              "target": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "x": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000
                      },
                      "y": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000
                      }
                    },
                    "required": [
                      "x",
                      "y"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "ref": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 1000
                      },
                      "snapshot_id": {
                        "type": "string",
                        "pattern": "^snp_[a-z2-7]{12}$"
                      }
                    },
                    "required": [
                      "ref",
                      "snapshot_id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      },
                      "nth": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 50
                      }
                    },
                    "required": [
                      "text"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 300
                      }
                    },
                    "required": [
                      "id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "desc": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      }
                    },
                    "required": [
                      "desc"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            },
            "required": [
              "type",
              "target"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "long_press"
              },
              "target": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "x": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000
                      },
                      "y": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000
                      }
                    },
                    "required": [
                      "x",
                      "y"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "ref": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 1000
                      },
                      "snapshot_id": {
                        "type": "string",
                        "pattern": "^snp_[a-z2-7]{12}$"
                      }
                    },
                    "required": [
                      "ref",
                      "snapshot_id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      },
                      "nth": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 50
                      }
                    },
                    "required": [
                      "text"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 300
                      }
                    },
                    "required": [
                      "id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "desc": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      }
                    },
                    "required": [
                      "desc"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "duration_ms": {
                "default": 800,
                "type": "integer",
                "minimum": 300,
                "maximum": 5000
              }
            },
            "required": [
              "type",
              "target"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "swipe"
              },
              "from": {
                "type": "object",
                "properties": {
                  "x": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000
                  },
                  "y": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000
                  }
                },
                "required": [
                  "x",
                  "y"
                ],
                "additionalProperties": false
              },
              "to": {
                "type": "object",
                "properties": {
                  "x": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000
                  },
                  "y": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000
                  }
                },
                "required": [
                  "x",
                  "y"
                ],
                "additionalProperties": false
              },
              "duration_ms": {
                "default": 300,
                "type": "integer",
                "minimum": 50,
                "maximum": 5000
              }
            },
            "required": [
              "type",
              "from",
              "to"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "scroll"
              },
              "direction": {
                "type": "string",
                "enum": [
                  "up",
                  "down",
                  "left",
                  "right"
                ]
              },
              "target": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "x": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000
                      },
                      "y": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 10000
                      }
                    },
                    "required": [
                      "x",
                      "y"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "ref": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 1000
                      },
                      "snapshot_id": {
                        "type": "string",
                        "pattern": "^snp_[a-z2-7]{12}$"
                      }
                    },
                    "required": [
                      "ref",
                      "snapshot_id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      },
                      "nth": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 50
                      }
                    },
                    "required": [
                      "text"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 300
                      }
                    },
                    "required": [
                      "id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "desc": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      }
                    },
                    "required": [
                      "desc"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "amount": {
                "default": 0.6,
                "type": "number",
                "minimum": 0.1,
                "maximum": 1
              }
            },
            "required": [
              "type",
              "direction"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "type"
              },
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 5000
              },
              "clear": {
                "default": false,
                "type": "boolean"
              },
              "submit": {
                "default": false,
                "type": "boolean"
              }
            },
            "required": [
              "type",
              "text"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "key"
              },
              "key": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "enter",
                      "delete",
                      "tab",
                      "escape",
                      "space",
                      "up",
                      "down",
                      "left",
                      "right",
                      "page_up",
                      "page_down",
                      "move_home",
                      "move_end",
                      "menu",
                      "search",
                      "volume_up",
                      "volume_down"
                    ]
                  },
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 400
                  }
                ]
              }
            },
            "required": [
              "type",
              "key"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "back"
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "home"
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "recents"
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "notifications"
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "open_app"
              },
              "package": {
                "type": "string",
                "maxLength": 255,
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z0-9_]+)+$"
              },
              "activity": {
                "type": "string",
                "maxLength": 300
              }
            },
            "required": [
              "type",
              "package"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "close_app"
              },
              "package": {
                "type": "string",
                "maxLength": 255,
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z0-9_]+)+$"
              },
              "clear_data": {
                "default": false,
                "type": "boolean"
              }
            },
            "required": [
              "type",
              "package"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "open_url"
              },
              "url": {
                "type": "string",
                "minLength": 3,
                "maxLength": 2000
              },
              "package": {
                "type": "string",
                "maxLength": 255,
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z0-9_]+)+$"
              }
            },
            "required": [
              "type",
              "url"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "wait"
              },
              "ms": {
                "type": "integer",
                "minimum": 1,
                "maximum": 10000
              }
            },
            "required": [
              "type",
              "ms"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "wait_for"
              },
              "target": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      },
                      "nth": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 50
                      }
                    },
                    "required": [
                      "text"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 300
                      }
                    },
                    "required": [
                      "id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "desc": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      }
                    },
                    "required": [
                      "desc"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "gone": {
                "default": false,
                "type": "boolean"
              },
              "timeout_ms": {
                "default": 10000,
                "type": "integer",
                "minimum": 100,
                "maximum": 30000
              }
            },
            "required": [
              "type",
              "target"
            ],
            "additionalProperties": false
          }
        ]
      },
      "description": "From 1 to 20 actions, run in order. Durations are in milliseconds, and the waits in one batch may add up to 60 seconds. Coordinates are device pixels."
    },
    "observe": {
      "default": "ui",
      "description": "What the result shows of the screen afterwards: ui (the element list, the default), screenshot, both, or none. A batch that stops early shows the element list, unless the screen couldn't be read, or not in time.",
      "type": "string",
      "enum": [
        "none",
        "ui",
        "screenshot",
        "both"
      ]
    }
  },
  "required": [
    "phone_id",
    "actions"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

reboot_phone

Restart a phone that is stuck, keeping everything on it, and wait until it is ready again. A phone can reboot once every 10 minutes; a reboot the phone service didn't confirm is never sent twice: wait for ready with get_phone instead. If it is still creating or starting when this returns, call get_phone with its ID and wait "ready" to keep waiting: it only reads, while start_phone would renew the session.

Parameters1

phone_id

string

required

Phone ID from create_phone or list_phones.

Raw schema

{
  "type": "object",
  "properties": {
    "phone_id": {
      "type": "string",
      "pattern": "^ph_[a-z2-7]{12}$",
      "description": "Phone ID from create_phone or list_phones."
    }
  },
  "required": [
    "phone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

list_apps

List the apps installed on a phone: package, label, version and whether it came with the phone. Open one with act and open_app.

Parameters1

phone_id

string

required

Phone ID from create_phone or list_phones.

Raw schema

{
  "type": "object",
  "properties": {
    "phone_id": {
      "type": "string",
      "pattern": "^ph_[a-z2-7]{12}$",
      "description": "Phone ID from create_phone or list_phones."
    }
  },
  "required": [
    "phone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

install_app

Install an app from Phonebox's app library by package name, in the background. It doesn't reach Google Play: to get a Play Store app, open the Play Store app on the phone with act and install it there. To check on an install later, open the app with act: open_app answers app_not_found until the install has finished. With upload instead of package, it installs your own APK (see create_app_upload) and waits until the phone lists the app, or says why it failed. While that upload is still installing on the phone, and for 10 minutes after that install succeeds, calling install_app again with it starts nothing: a repeat only waits for it, or reports it.

Parameters4

phone_id	string	required	Phone ID from create_phone or list_phones.
package	string	optional	The app's Android package name, such as com.whatsapp: an app from Phonebox's app library. Give this or upload.
upload	string	optional	An upload of your own APK whose status is ready, from complete_app_upload. Give this or package.
replace	boolean	optional	With upload: uninstall the app first when it is on the phone, which deletes its data. Use it for a build signed with another key, or an older version_code.

Raw schema

{
  "type": "object",
  "properties": {
    "phone_id": {
      "type": "string",
      "pattern": "^ph_[a-z2-7]{12}$",
      "description": "Phone ID from create_phone or list_phones."
    },
    "package": {
      "description": "The app's Android package name, such as com.whatsapp: an app from Phonebox's app library. Give this or upload.",
      "type": "string",
      "maxLength": 255,
      "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z0-9_]+)+$"
    },
    "upload": {
      "description": "An upload of your own APK whose status is ready, from complete_app_upload. Give this or package.",
      "type": "string",
      "pattern": "^upl_[a-z2-7]{12}$"
    },
    "replace": {
      "description": "With upload: uninstall the app first when it is on the phone, which deletes its data. Use it for a build signed with another key, or an older version_code.",
      "type": "boolean"
    }
  },
  "required": [
    "phone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

create_app_upload

Start an upload of your own APK, such as the debug build you just made, to install it on a phone. MCP can't carry a file, so this returns a one-off upload_url and the exact curl command to send the APK there from your shell; then call complete_app_upload with the storageId it answers. Send the URL one file of up to 500 MiB, within an hour.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

complete_app_upload

Finish an upload once its file has arrived, and wait while Phonebox reads and stores the APK. It answers with the upload: ready to install with install_app, or ended with an error saying why. If it is still processing when this returns, call it again with the same arguments: a repeat only waits.

Parameters2

upload_id	string	required	The upload's ID, from create_app_upload.
storage_id	string	required	The storageId that upload_url answered with, as {"storageId": "…"}.

Raw schema

{
  "type": "object",
  "properties": {
    "upload_id": {
      "type": "string",
      "pattern": "^upl_[a-z2-7]{12}$",
      "description": "The upload's ID, from create_app_upload."
    },
    "storage_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[\\w;:-]+$",
      "description": "The storageId that upload_url answered with, as {\"storageId\": \"…\"}."
    }
  },
  "required": [
    "upload_id",
    "storage_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

live_view_url

Create a link a human can open to watch and control the phone, for example to sign in or solve a check. The link expires (default one hour). Anyone with the link controls the phone until it expires; share it only with your user and never paste it into logs or shared chats.

Parameters2

expires_in	integer	optional	Seconds until the link stops working, from 60 to 86400. The default is 3600.
phone_id	string	required	Phone ID from create_phone or list_phones.

Raw schema

{
  "type": "object",
  "properties": {
    "expires_in": {
      "default": 3600,
      "description": "Seconds until the link stops working, from 60 to 86400. The default is 3600.",
      "type": "integer",
      "minimum": 60,
      "maximum": 86400
    },
    "phone_id": {
      "type": "string",
      "pattern": "^ph_[a-z2-7]{12}$",
      "description": "Phone ID from create_phone or list_phones."
    }
  },
  "required": [
    "phone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md5 KBView on GitHub

Phonebox Android MCP server

A hosted Android MCP server for Claude Code, Codex, Cursor and any MCP client, from Phonebox, the agent-first cloud phone. Your agent gets a real Android phone in the cloud. It can read the screen, tap, type, install your APK, hand off to a human, and park the phone when it's done. You don't need ADB, Android Studio or an emulator.

bash

claude mcp add --transport http phonebox https://phonebox.dev/mcp \
  --header "Authorization: Bearer $PHONEBOX_API_KEY"

Endpoint: https://phonebox.dev/mcp (Streamable HTTP, bearer API key)
Price: $0.06 per phone-minute, billed per second, 1-minute minimum. Parked phones are free and keep their apps and sign-ins.
Start free: $2 of credit, no card → phonebox.dev

This repo holds the configs and examples. The server itself is hosted by Phonebox, so there's nothing to run.

Why agent-first

Most cloud phones were built for social-media dashboards or QA test suites and added an API later. Phonebox was built for the agent: your agent signs you up from the terminal, reads the screen as text, gets errors with a next step, and never has a write retried behind its back. Idle phones park themselves for free.

Why hosted instead of an ADB MCP server?

	Local ADB MCP server	Phonebox hosted MCP
Where the phone runs	An emulator or USB phone on your machine	Phonebox's cloud
Setup	Android SDK, ADB, a system image	One URL and an API key
Works from CI, sandboxes and remote dev boxes	Only with nested virtualization or a device	Yes
State between sessions	Whatever your emulator keeps	Apps, files and sign-ins kept while parked
Human handoff	Someone at the machine	A live view link in any browser

Get an API key

The fastest way is to paste this into your coding agent. It signs you up from the terminal, and you never paste a key into the chat:

text

Read https://phonebox.dev/setup.md and set me up with Phonebox from here: get me signed in and ready, then find out what I want to use phones for and help me with that.

Or create a key in the console and export PHONEBOX_API_KEY=pbx_….

Connect your client

Claude Code — run the command at the top, or commit this repo's .mcp.json. It reads the key from each person's environment:

json

{
  "mcpServers": {
    "phonebox": {
      "type": "http",
      "url": "https://phonebox.dev/mcp",
      "headers": { "Authorization": "Bearer ${PHONEBOX_API_KEY}" }
    }
  }
}

Cursor: add examples/cursor-mcp.json to ~/.cursor/mcp.json or .cursor/mcp.json.

Codex: add examples/codex-config.toml to ~/.codex/config.toml.

Any other client: point it at https://phonebox.dev/mcp with an Authorization: Bearer pbx_… header. The server is stateless Streamable HTTP and doesn't use OAuth.

Tools

Tool	What it does
`create_phone`	Creates a cloud Android phone and waits until it's ready
`observe`	Reads the screen as a numbered text list, plus a 720px screenshot
`act`	Runs up to 20 actions in order: tap, type, swipe, scroll, open an app, wait for an element
`install_app`	Installs from the app library or from your own uploaded APK
`create_app_upload` / `complete_app_upload`	Uploads your APK with one `curl` command
`live_view_url`	A link for a person to watch and control the phone
`start_phone` / `park_phone`	Resumes a parked phone, or parks it to stop billing
`list_phones` / `get_phone` / `list_apps` / `reboot_phone`	Find phones, wait for them, list apps, restart a stuck phone

What the agent reads from observe:

text

app com.android.launcher3
screen 1080x2400
[1] EditText "Search apps" #search clickable editable (540,250)
[2] TextView "Chrome" #icon clickable (200,1900)
[3] TextView "Settings" #icon clickable (500,1900)

Examples

Test the APK you just built: build, install, explore, and report bugs with the exact screen text.
TypeScript SDK agent: create a phone, read the screen, tap, park.

What it isn't

Android only (no iOS), and there are no phone numbers, SMS or calls. Phonebox gives your agent the device, not telephony.

Learn more

Install

Tools (13)

list_phonescreate_phoneget_phonestart_phonepark_phoneobserveactreboot_phone

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://phonebox.dev/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "phonebox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://phonebox.dev/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

Topics

list_phones

create_phone

get_phone

start_phone

park_phone

observe

act

reboot_phone

list_apps

install_app

create_app_upload

complete_app_upload

live_view_url

Phonebox Android MCP server

Why agent-first

Why hosted instead of an ADB MCP server?

Get an API key

Connect your client

Tools

Examples

What it isn't

Learn more

Install

Remote endpoint

Related servers