Android DevTools MCP

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.

Related MCP server: Android MCP Server

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

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.