To give Gemini CLI an Android phone, add the Mobilebox MCP server to ~/.gemini/settings.json with httpUrl set to https://mobilebox.dev/mcp and your API key in an Authorization header read from the environment. Gemini CLI then has 14 phone tools: it starts a cloud Android phone, installs your APK, reads the screen, taps, types, takes screenshots and stops the phone when it is done.

The shortest way: let the agent do it

Paste this into Gemini CLI:

text
Set up Mobilebox for me: read https://mobilebox.dev/setup.md and follow it.

It asks for your email, gets a key at once, stores it without printing it and adds the server; the 6-digit code from your inbox keeps the workspace.

Add the server by hand

Put your key in your shell profile as MOBILESANDBOX_API_KEY (sign up and create one in the dashboard, or let the agent get one through setup.md) and open a new terminal. Then add this to ~/.gemini/settings.json for every project, or .gemini/settings.json for one:

json
{
  "mcpServers": {
    "mobilebox": {
      "httpUrl": "https://mobilebox.dev/mcp",
      "headers": { "Authorization": "Bearer ${MOBILESANDBOX_API_KEY}" }
    }
  }
}

httpUrl is Gemini CLI’s field for a Streamable HTTP server; url on its own means the older SSE transport. Gemini CLI fills in ${MOBILESANDBOX_API_KEY} from your environment when it starts, so the key never sits in the file.

The same server from the command line. The single quotes keep the variable unexpanded, and the CLI writes it as url with "type": "http", which also connects over Streamable HTTP:

bash
gemini mcp add --scope user --transport http mobilebox https://mobilebox.dev/mcp \
  --header 'Authorization: Bearer ${MOBILESANDBOX_API_KEY}'

Or sign in without a key

Gemini CLI speaks MCP OAuth. Add the entry with httpUrl alone, no headers, then run /mcp auth mobilebox inside Gemini CLI. Your browser opens, you sign in to Mobilebox and choose Allow, and Gemini CLI keeps the token in ~/.gemini/mcp-oauth-tokens.json. Mobilebox shows the connection under API keys in the dashboard, where you can revoke it.

Check it

Run /mcp in Gemini CLI, or gemini mcp list in the shell. The server should say Connected. If it says Disabled, the folder isn’t trusted: Gemini CLI turns MCP servers off in untrusted folders, user-level ones included, so trust the folder first.

Gemini CLI asks before each tool call. "trust": true on the server skips those questions; leave it off until you have watched a few runs.

The format comes from Gemini CLI’s own MCP server docs and its configuration reference, reviewed on November 10, 2026. We ran gemini mcp list on Gemini CLI 0.67.0 against production, with the exact file below and with the gemini mcp add command: Connected with the key set, Disconnected without it.

A first task

text
Start a Mobilebox phone, install the APK at <your APK URL>, walk the sign-up flow, take a screenshot of each step, then stop the phone.

Gemini CLI calls create_phone, which returns the first screen, then install_app with your URL. For each step of the flow it calls act to tap or type and gets the new screen back, and screenshot when you asked for the picture. Stopping is park_phone: the phone stops billing and keeps the app and its login for the next run. Say "delete the phone" instead when you want nothing kept. watch_phone gives you a link to watch it live. The mental model: a phone per agent per PR, started, checked, screenshotted, stopped.

What it costs

A phone costs $0.01 a minute while it is ready, billed per second with a one-minute minimum. Boot time and parked phones are free. On our November 8 benchmark one tap plus a fresh screenshot took 1.45 s at the median, so most of a run is your model thinking between steps. A sign-up walk that keeps the phone ready for 3 minutes costs 3 cents; our framework examples finished their short task in 31 to 38 seconds, about a cent. The agent guide covers the observe, act, verify loop in full.