io.github.dev-jackson/androidbuild-mcp

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.

No install step — npx fetches the server on first run.

Claude Code

claude mcp add androidbuild -- npx -y @asjackson/androidbuild-mcp

Any other MCP client

{
  "mcpServers": {
    "androidbuild": {
      "command": "npx",
      "args": ["-y", "@asjackson/androidbuild-mcp"]
    }
  }
}

Run from source instead

git clone https://github.com/dev-jackson/androidbuild-mcp.git
cd androidbuild-mcp
npm install && npm run build
claude mcp add androidbuild -- node /absolute/path/to/androidbuild-mcp/dist/index.js

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.

Tool reference

53 tools over stdio. Every tool takes plain arguments and returns text (or an image, for screenshot).

Environment and project

Session defaults

Build, test and quality

Devices and emulators

App lifecycle

UI automation

Logs and recording

Scaffolding

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.