AndroidBuildMCP

Give your AI agent hands on Android. AndroidBuildMCP is an MCP server that lets any MCP client (Claude Code, Cursor, ...) build, deploy, drive and debug real Android apps: Gradle builds with readable errors, emulator management, adb deployment, logcat capture and full UI automation.

Quick start

Requirements: Node 18+, the Android SDK (ANDROID_HOME or a default install), and a JDK 17+ for Gradle builds.

Install from source

git clone https://github.com/dev-jackson/androidbuild-mcp.git
cd androidbuild-mcp
npm install && npm run build

Claude Code

claude mcp add androidbuild -- node /absolute/path/to/androidbuild-mcp/dist/index.js

Any other MCP client

{
  "mcpServers": {
    "androidbuild": {
      "command": "node",
      "args": ["/absolute/path/to/androidbuild-mcp/dist/index.js"]
    }
  }
}

Pending: npm publish. Once the package is on npm, installation will be a single command: npx -y androidbuild-mcp — no clone or build needed.

Then ask your agent to run doctor — it checks the SDK, adb, emulator, Java and connected devices, and tells you exactly what is missing.

What your agent can do

• Build and test — build_app compiles and returns compact file:line compiler errors instead of a thousand lines of Gradle noise. test_app / test_instrumented return parsed pass/fail summaries. Lint, clean, coverage (Kover/Jacoco) included.
• Manage emulators — list, create, boot (waits for full boot, returns the serial), wipe, and kill AVDs. Set GPS location, dark mode, and a clean demo status bar for screenshots.
• Deploy — build_run compiles, installs and launches in one call. Install/uninstall/clear-data/app-info via adb, with the right device auto-selected when only one is connected.
• See the screen — snapshot_ui returns the UI as a compact list of named elements with tap coordinates (Compose semantics merged, noise filtered). screenshot returns an image; with annotate: true it draws numbered boxes using vision, catching text inside images and WebViews.
• Touch the screen — tap, scroll, swipe, drag, long-press, type (keyboard-aware, with clear/submit), hardware keys, and wait_for_ui to poll until an element appears.
• Read the logs — background logcat capture filtered to your app, one-shot dumps, and the crash buffer for stack traces.
• Start new apps — scaffold_android_project generates a minimal Compose project that builds out of the box.

Session defaults (session_set_defaults) mean you configure project, module, variant and device once — every other call then works without arguments.

Tapping accurately

Everything adb-side shares one coordinate space (device pixels), but MCP clients often display screenshots scaled — estimating pixel positions by eye from the image sends taps to the wrong place. Three safe ways to hit the target:

1. snapshot_ui — returns exact device-pixel centers for every named element. Preferred.
2. screenshot { annotate: true } + tap_element { element: N } — tap by the number drawn on the image; the mapping is resolved on the original PNG, so client-side scaling cannot distort it.
3. tap { xPct, yPct } — screen percentages (0-1), also available on long_press/swipe/drag. Resolution-independent.

Raw tap { x, y } still works when you have real pixel coordinates.

Reliability

Every tool was exercised against real emulators and real projects — happy paths and corner cases — before release; the scenario-by-scenario evidence is in qa-results.md. Some of the details that keep agent flows from misfiring:

• type_text waits for the soft keyboard before injecting (typing right after focusing a field silently drops the first characters otherwise).
• scroll computes a long, slow swipe from the screen size — short fast swipes get ignored by some lists. long_press holds 1000 ms, which launchers require.
• Taps outside the screen are rejected with the actual screen size instead of silently doing nothing.
• Text-heavy screens (e-book WebViews and the like) are capped and searchable with snapshot_ui { filter } instead of flooding the context.
• Build/test/device failures come back as short, actionable messages with the next tool to call.

Optional extras

• Google's Android CLI enables screenshot { annotate: true }. doctor prints the one-line installer for your OS.
• The ADBKeyboard IME enables non-ASCII type_text (adb alone is ASCII-only). Install its APK once; the server uses it automatically.

Development

npm install
npm test            # unit tests (no real processes spawned)
npm run dev         # run the server from source
npm run build       # compile to dist/

License

MIT — see LICENSE.

Conceptually inspired by XcodeBuildMCP; independent implementation built around the Android toolchain.