mobile-mcp-image

Container image for mobile-next/mobile-mcp, which has no published image, bundled with adb so it can drive an Android phone over Wi-Fi adb from a Kubernetes Pod or any container host.

• Unmodified upstream: @mobilenext/mobile-mcp from npm, every dependency pinned by package-lock.json (version + sha512). This repo only adds an entrypoint.

• adb: Google Android SDK Platform-Tools, pinned by sha256.

• Runtime: gcr.io/distroless/nodejs22-debian13 — no shell, no package manager; runs as uid 1000.

• Image: ghcr.io/mouse9527/mobile-mcp-image:sha-<short commit> (linux/amd64; built only from main; no latest).

What the entrypoint does

1. Refuses to start unless MOBILEMCP_AUTH is set (mobile-mcp otherwise serves without authentication), or MOBILEMCP_AUTH_DISABLED=1 explicitly allows that (for use behind an authenticating proxy). Setting both is an error.

2. Copies $ADB_KEY_DIR/adbkey to ~/.android/adbkey with mode 0600, so the phone's pairing survives restarts. adb derives the public key from the private key; no adbkey.pub is needed.

3. Starts the adb server with mDNS off (ADB_MDNS=0; container networks usually drop multicast).

4. If PHONE_ADDR is set, checks every KEEPALIVE_SECONDS whether the phone is connected and runs adb connect on each of PHONE_ADB_PORTS until one works. It logs one line only when the state changes.

5. Starts mobile-mcp's Streamable HTTP server on MCP_LISTEN (/mcp), in the same process.

Telemetry (PostHog, scarf.sh) is off by default (MOBILEMCP_DISABLE_TELEMETRY=1).

Related MCP server: phone-mcp-server

Environment

Writable paths needed with a read-only root filesystem: $HOME (default /tmp/home) — mount an emptyDir on /tmp.

Run

# generate a key once and keep it; pairing is bound to it
openssl genrsa -traditional -out adbkey 2048

docker run --rm -p 8931:8931 \
  -e MOBILEMCP_AUTH="$(openssl rand -hex 32)" \
  -e PHONE_ADDR=<phone host or IP> \
  -e ADB_KEY_DIR=/keys -v "$PWD/adbkey:/keys/adbkey:ro" \
  ghcr.io/mouse9527/mobile-mcp-image:sha-<short commit>

Pair the phone once from inside the container (Android 11+: Developer options → Wireless debugging → Pair device with pairing code):

docker exec -it <container> adb pair <phone>:<pairing port>     # enter the 6-digit code
docker exec -it <container> adb connect <phone>:<debug port>
docker exec -it <container> adb -s <phone>:<debug port> tcpip 5555   # switch to a fixed port

After a phone reboot tcpip 5555 is lost: re-enable Wireless debugging and run the last two commands again with the new port.

Lease gateway (optional, PHONE_LEASE=1)

When several agents share one phone through an MCP gateway that opens a new upstream session for every tool call (LiteLLM does), per-session locking is useless and multi-step tasks interleave (agent A reads the screen, agent B opens another app, agent A taps). With PHONE_LEASE=1 the entrypoint puts a small gateway (gateway.js, same process, no dependencies) on MCP_LISTEN and moves mobile-mcp to LEASE_INNER_LISTEN (default 127.0.0.1:8932). mobile-mcp itself is unchanged; with the variable unset nothing changes.

• One holder at a time. A holder's tool call takes the phone if it is free and nobody is queued; every call extends the lease to now + LEASE_IDLE_S. Others wait FIFO inside their call for up to LEASE_WAIT_S, then get a tool error (isError) saying the phone is busy and their queue position (kept LEASE_TICKET_S, while someone holds the phone). When the lease ends, the first caller still waiting in a call gets it, reserved LEASE_GRACE_S for its next call; queued callers that are not waiting any more are skipped, so the phone is never parked for someone who left. State is in memory: a restart frees the phone.

• Who is the holder (first match): x-phone-holder header (set by the client's MCP config) > x-openwebui-chat-id (Open WebUI) > the client's MCP session id at the gateway in front, forwarded as mcp-session-id (mobile-mcp is stateless, so it is on every request) > nothing (call-level exclusion only, never keeps the phone). A client session seen for the first time only gets LEASE_SESSION_FIRST_IDLE_S, so callers that open a new session per call do not wait behind themselves. LiteLLM: list mcp-session-id, x-openwebui-chat-id, x-phone-holder in the server's extra_headers.

• Extra tools in tools/list: lease_status, lease_hold (seconds, keep the phone while waiting for the user, capped at LEASE_HOLD_MAX_S), lease_release. LEASE_TOKENS=1 also adds lease_acquire and an optional lease argument on every tool, for callers that cannot be identified otherwise (off by default: it changes tool schemas).

• Logs: one JSON line per event on stderr ("src":"lease"): time, event, a sha256 prefix of the holder, how it was identified, tool name, wait time. Never arguments, results or raw holder ids.

Screen helpers (optional, with the lease gateway)

• PHONE_WAKE=1: before a tool that needs the screen, the gateway checks dumpsys power (at most every WAKE_CHECK_S, default 15 s, also refreshed by every successful call). If the screen is not Awake: KEYCODE_WAKEUP (never POWER, which toggles), wm dismiss-keyguard (for phones without a lock-screen password), wait WAKE_SETTLE_MS (800), check again; still off → a clear tool error, mobile-mcp is not called. A read-only call (elements, foreground app, screenshot) that still finds no UI hierarchy gets one recovery round (screen on: VOLUME_UP + VOLUME_DOWN, which ends MIUI's pocket mode; screen off: WAKEUP again) and one retry, then a clear error. Uses the adb server of the container.

• ELEMENTS_TRIM=1: shorter mobile_list_elements_on_screen text (also inside mobile_batch_commands): identical overlapping elements listed once, zero-size ones dropped, resource ids without the package prefix, a label equal to the text written once, centre point c=x,y instead of the top-left corner. No visible string is dropped and refs keep their original numbers (taps by ref re-read the screen). format=json is not touched.

• Both off unless set; with both off tool calls are passed through unchanged. Log events: screen_woken, screen_recover, screen_still_no_ui, screen_check_failed.

Security notes

• Anyone holding the Bearer token can fully control the phone (tap, type, install / uninstall apps, open any URL scheme). Keep the endpoint on a private network and restrict who can reach it.

• The adb server listens only inside the container; do not publish adb ports.

Upgrading

• mobile-mcp: change the version in package.json, then regenerate the lockfile from the public npm registry: npm install --package-lock-only --ignore-scripts --omit=dev --registry https://registry.npmjs.org. Check the upstream changelog for new tools and update the expected tool count in smoke.sh.

• platform-tools: change PLATFORM_TOOLS_VERSION and PLATFORM_TOOLS_SHA256 in the Dockerfile. Google's repository manifest (https://dl.google.com/android/repository/repository2-3.xml) lists sha1 only; download the zip, check its sha1 against the manifest, then record its sha256.

• Base images: update the digests in NODE_IMAGE / RUNTIME_IMAGE; keep both on the same Debian release.

CI

.github/workflows/image.yml: build linux/amd64 → audit.sh (no adb keys, credentials or .git in the image; file list and hashes uploaded as an artifact) → smoke.sh (refuses to start without a token, 401 without token, 33 tools, adb ≥ 37, uid 1000, no shell, telemetry off; lease gateway with PHONE_LEASE=1: queueing, release, FIFO, hold, holder identity, first-call probation — smoke/lease_test.py) → push to ghcr from main only.

License

MIT for the files in this repository (LICENSE). The image also contains third-party software under its own licenses; see NOTICE.md.