# Gemini CLI on Android: add a cloud phone over MCP

The exact ~/.gemini/settings.json entry and gemini mcp add command for the Mobilebox MCP server, OAuth with /mcp auth, trusted folders, a first prompt and what a run costs.

Guides4 min read

In this article

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:

```
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](https://mobilebox.dev/signup) 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:

```
{
  "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:

```
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](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) and its [configuration reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md), 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

```
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](https://mobilebox.dev/benchmarks) 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](https://mobilebox.dev/integrations) finished their short task in 31 to 38 seconds, about a cent. The [agent guide](https://mobilebox.dev/docs/agents) covers the observe, act, verify loop in full.

## Try it in your agent in 60 seconds

Paste this into Claude Code, Cursor, Codex or any agent that can read a web page. It asks for your email, gets its own key at once and adds the phone tools; the 6-digit code from your inbox keeps the workspace.

```
Set up Mobilebox for me: read https://mobilebox.dev/setup.md?via=gemini-cli-android-mcp and follow it.
```

[What your agent reads](https://mobilebox.dev/setup.md?via=gemini-cli-android-mcp)

In this article

[All articles](https://mobilebox.dev/blog)

## Next questions

- [Is there a Python package?](https://mobilebox.dev/blog/android-phone-for-python-ai-agent?via=next-python)

- [Mobilebox or Firebase Test Lab?](https://mobilebox.dev/blog/mobilebox-vs-firebase-test-lab?via=next-firebase)

- [Mobilebox or BrowserStack?](https://mobilebox.dev/blog/mobilebox-vs-browserstack?via=next-browserstack)

- [Cloud phone or a local emulator?](https://mobilebox.dev/blog/mobilebox-vs-local-emulator?via=next-emulator)

- [Mobilebox, Limrun or Mobilerun?](https://mobilebox.dev/blog/mobilebox-vs-limrun?via=next-limrun)

- [How do I add it to Cursor, Codex or VS Code?](https://mobilebox.dev/blog/android-mcp-cursor-codex-vscode?via=next-setup)

- [Can my agent run 50 phones in parallel?](https://mobilebox.dev/blog/run-android-phones-in-parallel?via=next-parallel)

- [Can my agent use an iPhone?](https://mobilebox.dev/ios?via=next-iphone)