adb-mcp: Android emulator and device control over adb

adb-mcp

An [MCP](https://modelcontextprotocol.io) server that drives Android emulators and devices over `adb`

---

Boot an AVD, screenshot, read the UI hierarchy, tap/swipe/type, set a device lock, read logcat, run Gradle builds and tests. 80 tools, from Claude Code, Cursor, VS Code, or any MCP client over stdio.

It is the Android counterpart to XcodeBuildMCP, built on the official Go MCP SDK.

describe_ui → tap_on_text → screenshot, driven live against a real emulator (emulator-5556), showing the actual tool calls and their actual output.

Android is a trademark of Google LLC. adb-mcp is an independent, unofficial

tool built for Android and is not affiliated with, sponsored, or endorsed by Google.

The Android robot above is reproduced/modified from work created and shared by

Google and used according to terms described in the

Creative Commons 3.0 Attribution License.

Why

Driving Android by hand means a long runbook of raw adb commands, and it is easy to get wrong (stale tap coordinates, CRLF-corrupted screenshots, forgetting exec-out, guessing coordinates off a downscaled image). This server bakes that knowledge into its tools, so the agent doesn't have to relearn it:

• Screenshots use exec-out screencap (no CRLF corruption) and are auto-downscaled so the image reader accepts them.
• describe_ui returns each element's center in true device pixels (so taps land where you mean them to, no guessing off the image) and retries the transient "could not get idle state" failure on its own.

The workflow itself ships as readable resources the agent can pull up mid-task (the observe→act loop, native PIN/lock handling, crash triage, see below) instead of relearning them each session.

Getting started

1. Prerequisites

• Android SDK with platform-tools (adb) and emulator. The server finds it via $ANDROID_HOME / $ANDROID_SDK_ROOT, else the platform default (~/Library/Android/sdk on macOS). If your MCP client launches the server without those set, pass --sdk /path/to/sdk in the client config's args (the server then exports it, so Gradle finds the SDK too). doctor prints the location it resolved.
• At least one AVD (create one in Android Studio's Device Manager).

Go is not required: releases ship prebuilt binaries, and it's only needed to build from source.

2. Install

On macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/iksnerd/adb-mcp/main/install.sh | sh

The script (install.sh) picks the right archive for your OS/architecture, verifies its SHA-256 against the release's checksums.txt, and installs to ~/.local/bin (override with BIN_DIR=...; pin a version with VERSION=v0.24.3).

Prefer to grab the binary yourself? Every platform's archive (macOS, Linux, and Windows, amd64 and arm64) is on the Releases page, each with a checksum in checksums.txt. On Windows, download the windows_amd64 or windows_arm64 zip and put adb-mcp.exe somewhere on your PATH.

Once installed, stay current with the built-in updater. It fetches the latest release, verifies its checksum, and swaps the binary in place:

adb-mcp update

The registration below launches the server by the bare name adb-mcp, so it must be on your $PATH (which adb-mcp should resolve; the installer warns if ~/.local/bin isn't on it). Otherwise point the client at the absolute path to the binary instead.

3. Register with your MCP client

Claude Code:

claude mcp add adb -- adb-mcp

(When working inside this repo itself, the bundled .mcp.json is picked up automatically, no registration needed.)

Or install as a plugin, which registers the server and adds a skill per driving guide:

claude plugin marketplace add iksnerd/adb-mcp

claude plugin install adb-mcp@adb-mcp

Register the server one way, not both. claude mcp add and the plugin each register it, under different names (adb and plugin:adb-mcp:adb), so using both gives a session two copies of all the tools and no clear one to call. If you added it with claude mcp add and then install the plugin, remove the first (claude mcp remove adb).

For Codex, the same plugin ships in Codex's manifest shape:

codex plugin marketplace add iksnerd/adb-mcp

codex plugin add adb-mcp@adb-mcp-plugins

The Claude plugin starts the server with node, which downloads the build for your machine from the GitHub release on first run and checks it against a pinned SHA-256, so it needs Node on your PATH but not step 2. The Codex plugin still expects adb-mcp on your PATH from step 2. What the plugin runs and sends is in docs/PRIVACY.md.

Cursor / VS Code: one-click install (assumes adb-mcp is on your PATH from step 2):

Any other client (Windsurf, Codex, …): run adb-mcp over stdio. The usual config shape:

{

"mcpServers": { "adb": { "command": "adb-mcp" } } }

To confirm it's wired up, ask your agent to "boot an emulator and take a screenshot".

From source (Go 1.26+)

The module pins toolchain go1.26.10; a Go 1.26 install downloads that patch itself the first time you build.

make install                 # builds ./bin/adb-mcp and copies it to ~/.local/bin

or:

go build -o bin/adb-mcp ./cmd/adb-mcp

or straight from the module (note the /cmd/adb-mcp suffix):

go install github.com/iksnerd/adb-mcp/cmd/adb-mcp@latest

Tools

80 tools across ten areas. Every device-facing tool takes an optional serial (adb -s). Omit it with one device attached, or pass one from list_devices with several. Full reference: docs/TOOLS.md.

• Emulator / device: boot, list, wait-for-boot, shut down, connect over Wi-Fi, adb_reverse port forwarding (Metro!)
• Observe: screenshot to see (works on multi-display foldables, pick a panel with display), describe_ui for true-pixel element centers, with the focused top window (spot a biometric prompt, or the wrong app entirely, occluding your target via optional package), filter/query/compact modes, and a hidden-node count so absence is trustworthy; render_stats counts the real view tree and frame health, which the viewport-scoped describe_ui cannot
• Interact: tap, tap_on_text/tap_element (id-addressed), swipe, drag, long-press, type, key combos, PIN pads, wait, run_sequence (batch steps + guards in one call, which keeps native-timer flows from being perturbed by per-step round-trips); opt-in verify_change tells you whether a tap/key actually changed the UI; opt-in via_accessibility on tap_on_text/tap_element (EXPERIMENTAL) dispatches a real accessibility click for native views a coordinate tap can't reach, see bridge/README.md
• Lock / Keystore / Biometrics: set/clear a secure lock screen, check lock state, has_biometric_enrolled + fingerprint_touch/finger_remove to satisfy a BiometricPrompt on the emulator
• Extended Controls (emulator): send_sms (OTP/2FA), phone_call, set_battery (also works on real devices via dumpsys), cellular (roaming/weak-signal/throttled), set_sensor (accelerometer/light/…), rotate_screen, avd_snapshot, driving the emulator's console-only panel that describe_ui can't see
• App lifecycle: install/uninstall, launch/stop, get_app_details (version and launcher activity of an installed app, or of a local APK via apk_path with no device), app_state (running pid(s) + Metro-vs-embedded bundle), launch_dev_client (Expo dev build → Metro, skipping the Dev Launcher), reload_app/open_dev_menu, clear data, permissions, deep links, push/pull files
• Logs & capture: one-shot or streaming logcat (substring/priority/tag filters, since time window, opt-in redact to mask tokens/passwords/API keys before output), clear_logcat, last_crash, screen recording
• Environment & diagnostics: dark mode, mock location, clean status bar, stay_awake (stop a doze-happy screen blanking your screenshots), doctor
• Gradle build & test: assembleDebug, unit tests, instrumented tests, JVM unit-test coverage via JaCoCo (get_coverage_report/get_file_coverage), task + variant + module discovery (list_gradle_variants/list_gradle_projects), scaffold_android_project, one-shot build_and_run. Builds return a compact summary (status, error count, first errors, APKs) with the full redacted log on disk, and gradle_build background=true plus build_status keep a multi-minute build from holding the call open
• Session defaults: pin project_dir/serial once (session_set_defaults) so a multi-module/multi-flavor project or multi-device session doesn't need them repeated on every call

The driving know-how itself ships as six MCP resources (android://guide/*) the client can list and read. See docs/TOOLS.md for the URIs, or jump straight to android://guide/driving for the core loop below.

The core loop

observe → locate → act → re-observe. screenshot to see, describe_ui to get true-pixel centers, tap/tap_on_text/swipe/input_text to act, then screenshot again to confirm. Read android://guide/driving for the full loop and the gotchas that waste turns.

Development

make check     # go vet + go test + doc-count check (unit tests need no emulator)

make run # run over stdio for manual JSON-RPC poking

Layout:

cmd/adb-mcp/main.go        entry: subcommands (update/version) or serve MCP over stdio

internal/tools/ thin MCP tool bindings internal/adb/ the device layer: an adb.Client whose methods are the commands internal/gradle/ host-side Gradle: builds (summary, log, background jobs), secret redaction, test and coverage reports internal/uiauto/ pure uiautomator-hierarchy model + parsing (unit-tested) internal/sdk/ resolves the Android SDK (adb/emulator paths, PATH env) internal/concurrent/ RunAll/RunIndexed: fan out independent I/O calls, join, done internal/guides/ the skill guides, embedded and served as MCP resources internal/selfupdate/ the adb-mcp update release fetch/verify/swap internal/bridgeupdate/ the `adb