android-mcp

MCP server that lets an agent use the Android app you are developing, on a local emulator or a real device, the way a person does: look at the screen, tap, swipe, type, press keys, wait for things to appear and read logcat. It drives the devices through adb, so every device Android Studio sees works here too.

Only Android Studio dev builds

The server only works with apps installed by Run in Android Studio. A package qualifies when all of these hold (read from dumpsys package):

• DEBUGGABLE: a debug build.

• TEST_ONLY: Android Studio injects android:testOnly="true" into builds started from the IDE, and such APKs can only be installed with adb install -t, never through the Play Store or the package installer. A ./gradlew installDebug from the command line doesn't set it, so those installs are refused as well.

• initiatingPackageName=com.android.shell (Android 11+): installed over adb.

Enforcement:

• launch_app, stop_app, clear_app_data, open_url and logcat only accept such a package.

• Screen tools (get_ui, screenshot, wait_for, tap, long_press, swipe, scroll, type_text, press_key) check the foreground activity first and refuse while any other app is in front. The exception is the system permission dialog, so runtime permission prompts of the dev app can be answered.

• When an action leaves the app (e.g. press_key home), the response says so instead of showing the screen.

• There is no install tool: install via Android Studio.

Related MCP server: AndroidBuildMCP

On-device agent (fast UI reads)

The UI tree is read through Appium's UiAutomator2 server (appium-uiautomator2-server, Apache-2.0), which stays running on the device and keeps its accessibility connection open:

• A UI read takes ~0.4 s instead of 2.5–3 s with uiautomator dump, and it does not wait for the screen to become idle.

• Starting it costs ~2 s once per session. It is installed automatically the first time (two APKs: io.appium.uiautomator2.server and io.appium.uiautomator2.server.test). They are not dev builds, so the dev-app restriction never lets the tools drive them.

• Compose test tags are exposed as id= (mapTestTagToResourceId).

• If the agent can't be started, the tree falls back to uiautomator dump. Set ANDROID_MCP_AGENT=0 in the server's environment to always use the dump.

• Only one process can hold the accessibility connection, so the server is stopped before falling back to a dump, and other UiAutomator tools (Appium, Maestro) can't run against the device at the same time.

• Remove it from a device with adb uninstall io.appium.uiautomator2.server.test && adb uninstall io.appium.uiautomator2.server.

The APKs come from the npm dependency at install time; this repo does not redistribute them.

Setup

Requirements: Node 20+, the Android SDK platform-tools (adb) and, for AVDs, the emulator. The SDK is found via $ANDROID_HOME, $ANDROID_SDK_ROOT, ~/Android/Sdk, ~/Library/Android/sdk or PATH.

npm install
npm run build
claude mcp add --scope user android -- node "$PWD/dist/index.js"

During development npm run dev (tsx) runs the sources directly; rebuild and run /mcp → reconnect in Claude Code after changes.

Real devices

• USB: enable Developer options → USB debugging, plug in, accept the RSA prompt.

• Wi-Fi (Android 11+): Developer options → Wireless debugging → Pair device with pairing code, then adb pair <ip>:<pair-port> and adb connect <ip>:<port>.

When several devices are connected, every tool needs serial (from list_devices).

Tools

• One coordinate space. Screenshots are downscaled so the long edge is at most 768 px (image tokens grow with the pixel count). get_ui reports element centres in the same space, and every x/y input uses it, so a point read off a screenshot can be tapped as is. screenshot with region returns a sharper crop for reading small text; a crop's pixels are not screen coordinates.

• Stable refs. Every element has a [ref] that stays the same across calls as long as the element keeps its identity (class, id, label). Refs start at a random base per server process, so refs from before a restart fail instead of hitting another element.

• Act + observe in one call. Action tools wait settle_ms (300 ms default) and then report, by default (observe: "changes"), only what changed since the agent last saw the screen: added (+), changed (~) and gone (-) elements, or "No visible change". A new screen comes back in full. ui, screenshot, both and none are available too.

• read_all scrolls a list or form to its end and returns all entries in one call, instead of one call (and one model turn) per scroll.

• Targets. tap/long_press/type_text take index (a [ref]), text (text or content description, substring unless exact), id (resource id / Compose test tag), or x+y. Refs are looked up in a fresh read, so they always tap the element's current position.

• get_ui output lists only visible elements that carry text, a description, a leaf id or an interaction flag. A clickable container without its own text shows its children's text as ~"…", and those children are folded into it. all: true shows every node.

• No tree? If neither the agent nor uiautomator dump delivers a tree, the tools say so and get_ui returns a screenshot instead: continue with x/y taps.

• logcat filters by the app's uid, so lines of a crashed earlier process are still included. By default each call only returns lines that are new since the previous call with the same filters.

• Crash notices. Every screen tool and launch_app/open_url check the app for new crashes, ANRs and native crashes after acting (~75 ms) and put a ⚠ … crashed: <exception> at <frame> notice with the get_crash id in front of the result, or of the error if the action failed. Crashes that happen between two calls are reported with the next call; each crash is reported once.

• Animations off. On first use of a device the server sets the window, transition and animator duration scales to 0, so steps are faster and the UI is settled when it is read. The original values are restored when the server exits (also on SIGINT/SIGTERM and when the client closes stdin) and kept in $TMPDIR/android-mcp-animations-<serial>.json meanwhile, so a server that was killed hard doesn't make the next one treat 0 as original. If a server was killed hard (kill -9), the next server restores the device when it exits. Set ANDROID_MCP_KEEP_ANIMATIONS=1 to leave the settings alone.

• list_crashes / get_crash read the system DropBox (dumpsys dropbox): Java crashes, ANRs and native crashes of the app, newest first, each with exception and top frame; get_crash returns the full report with the complete stack trace. Unlike logcat, these reports survive the process and log rotation. since_minutes limits the list to recent crashes.

• start_emulator waits up to ~40 s per call (below the MCP request timeout); call it again to keep waiting. Emulator output goes to $TMPDIR/android-mcp-emulator-<avd>.log.

Token usage

Each tool call is one model turn, and every turn re-reads the whole conversation. Long UI sessions inside a big coding conversation get expensive because of that, not because of the tool output. Run UI testing in a fresh session or in a subagent with a small context: a ready-made Claude Code subagent definition (android-tester, Sonnet, android tools only) can live in ~/.claude/agents/android-tester.md.

Typical loop

1. Install the app with Run in Android Studio, then list_dev_apps.

2. launch_app → read the returned UI tree.

3. tap / type_text / scroll and read the new state from each response; wait_for text after navigation or loading instead of sleeping.

4. list_crashes to see whether the app crashed, get_crash for the stack trace, and logcat with level: "E" for errors that didn't crash it.

Limitations

• type_text supports printable ASCII only (adb shell input text). Use press_key enter for new lines.

• No multi-touch gestures (pinch). Zoom maps with double-tap or their zoom controls.

• Compose test tags appear as id= only if the app sets Modifier.semantics { testTagsAsResourceId = true } at its root (worth enabling in debug builds); otherwise target Compose elements by text or content description.

• Screenshots take ~1 s (screencap) and cost far more tokens than the tree; ask for them only where the tree is not enough.