mobila

One command → a real Android phone, controlled by Claude / ChatGPT / Cursor / any MCP client.

mobila boots a local Android emulator, installs apps for it, and exposes the whole thing as an MCP server that an AI client can drive — tap, type, swipe, screenshot, install — in plain English. Optionally publishes the MCP server on a stable public URL so the same phone is reachable from a remote ChatGPT Custom GPT or Claude Code on another machine.

Built on top of mobilerun (vendored under vendor/mobilerun; MIT, © Niels Schmidt) plus a small layer of glue — recipes, install helpers, MCP transport, persistent ngrok tunnel.

Status: macOS works end-to-end. Linux + Windows packaging — next release.

Install (macOS)

bash <(curl -fsSL https://raw.githubusercontent.com/mamayevets/mobila/main/scripts/install/mac.sh)

…or from a cloned repo:

git clone https://github.com/mamayevets/mobila && cd mobila
bash scripts/install/mac.sh

The bootstrap installs: Xcode Command-Line Tools, Homebrew, uv, and the mobila package itself as a uv tool.

Related MCP server: ADB MCP Server

First run

mobila setup     # Android SDK + scrcpy + AVD creation (~5 min, one-time)
mobila           # boots the phone + opens scrcpy mirror window

Daily use

Installing apps without a Google account

mobila install telegram                # presets: telegram, whatsapp, signal,
                                       # instagram, tiktok, youtube, gmail,
                                       # chrome, firefox, fdroid, aurora, spotify
mobila install com.spotify.music       # any package id (resolved via apkeep)
mobila install ~/Downloads/foo.apk     # local file
mobila install https://example.com/foo.apk

Presets and package-id installs need brew install apkeep.

AI control: mobila serve

mobila serve exposes the phone as an MCP server so AI clients can drive it. Three modes:

--http and --tunnel are protected by a Bearer token stored at ~/.mobila/token (chmod 600). The token survives restarts; rotate with mobila serve --rotate-token.

Public access in one wizard

mobila tunnel setup        # one-time: paste ngrok authtoken + dev domain
mobila serve --tunnel      # → https://<your-dev-domain>.ngrok-free.dev

We use ngrok's free-tier dev domain (one persistent *.ngrok-free.dev host per account) so the public URL stays the same across reboots, restarts, even reinstalls — register it once in your AI client and it keeps working. Setup walks you through both pastes:

─────────────────────────────────────────────────────────────
  mobila tunnel setup
─────────────────────────────────────────────────────────────
✓ ngrok installed

Step 1/2 — ngrok authtoken
  Opening https://dashboard.ngrok.com/get-started/setup/macos…
  Paste your authtoken: ***
✓ authtoken saved

Step 2/2 — your assigned dev domain
  Your dev domain: cute-name-xyz.ngrok-free.dev
✓ domain saved

  Done. Run: mobila serve --tunnel
  Your public URL is always:  https://cute-name-xyz.ngrok-free.dev

Tools the AI sees

• task_submit(prompt) — natural-language task → delegated to mobilerun

• task_logs / task_status / task_attach / task_kill — track that task

• phone_screenshot() → PNG

• phone_install(target) — preset / package id / URL / file

• phone_status() — is the emulator alive?

• dev_reload() — hot-reload the server (useful while iterating)

Wire it into Claude Code:

claude mcp add --transport http mobila https://<your-dev-domain>.ngrok-free.dev \
  --header "Authorization: Bearer $(mobila serve --show-token)"

…or into Claude Desktop / Cursor via JSON (mobila serve --tunnel prints the snippet on startup).

Tuning for your Mac

Override emulator resources via env vars:

AVD_RAM_MB=2048 AVD_CORES=4 mobila      # 16 GB Mac
AVD_RAM_MB=1024 AVD_CORES=2 mobila      # 8 GB Mac (default)

Platforms

• ✅ macOS (Apple Silicon + Intel)

• ⏳ Linux (via redroid) — next release

• ⏳ Windows (via WSL2 + redroid) — next release

License

MIT. Vendored mobilerun is also MIT — see vendor/mobilerun/UPSTREAM.md for the pinned upstream version and our patches.