Android DevTools

An MCP server that lets an agent inspect and operate an already-running Android emulator or physical device through ADB.

It provides a Chrome-DevTools-style workflow:

1. Capture a semantic UI snapshot or screenshot.
2. Identify a UI node.
3. Tap the revalidated node, type text, swipe, or press a key.
4. Inspect the resulting UI, foreground activity, and application logs.

The server talks to Android through ADB, not directly to QEMU. This keeps the same interface usable with Android Studio emulators, headless emulators, third-party QEMU frontends, and physical devices.

Requirements

• Node.js 20 or later
• Android SDK Platform Tools with adb available on PATH, or ADB_PATH set to the executable
• A booted device visible in adb devices -l
• USB debugging authorization accepted for physical devices

The server attaches to existing devices. It does not start AVDs, install APKs, or launch applications.

Build and run

npm install
npm run build
node dist/cli.js

The process uses MCP stdio, so its standard output is reserved for protocol messages. Operational messages are written to standard error.

Example MCP client configuration for this checkout:

{
  "mcpServers": {
    "android-devtools": {
      "command": "node",
      "args": [
        "<path-to-repo>/dist/cli.js"
      ],
      "env": {
        "ANDROID_SERIAL": "emulator-5554"
      }
    }
  }
}

ANDROID_SERIAL is optional when exactly one ready device is connected. Use ADB_PATH when adb is not on PATH.

Tools

Tool	Purpose
android_list_devices	List ready, offline, and unauthorized ADB devices
android_take_snapshot	Return a compact semantic UI hierarchy
android_take_screenshot	Return the current display as PNG
android_get_app_state	Inspect foreground activity, process, and display state
android_tap	Tap coordinates or a revalidated snapshot node
android_type_text	Clear and type into the focused field
android_swipe	Perform a coordinate-based swipe
android_press_key	Send Android key events
android_wait_for	Wait for a selector and semantic state
android_get_logs	Return bounded logcat lines for an app's current PIDs

Snapshot selectors use exact AND matching over resource ID, text, content description, class, and state flags. Node IDs are scoped to one snapshot. Before a node tap, the server captures a fresh hierarchy and verifies that the same semantic node still occupies the same bounds. It returns a stale or ambiguous-target error instead of tapping when that check fails.

Verification

npm run check
npm test
npm run build

There is also an opt-in smoke test for a disposable emulator. It sends the Home key and reads the current launcher's logs:

$env:ANDROID_MCP_TEST_SERIAL = "emulator-5554"
npm run test:device

Limitations

• UI Automator exposes the accessibility/semantic tree, not Android Studio's private Layout Inspector data.
• Canvas-rendered interfaces, games, protected windows, and some WebViews may only be inspectable through screenshots and coordinates.
• Compose elements need usable semantics to appear as distinct nodes.
• Text entry intentionally accepts only ADB-safe ASCII: letters, numbers, spaces, and .,_@+-/:=. Unicode input requires an optional device-side input method or instrumentation component and is not part of this release.
• Network tracing, CPU/memory profiling, frame timing, AVD lifecycle, and APK management are outside the current black-box scope.