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

Terminal

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

Any other MCP client

config.json

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

Run from source instead

bash

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

Tool	Description
`doctor`	Check SDK, adb, emulator, avdmanager, Java and connected devices; reports what is missing
`discover_projects`	Find Android/Gradle projects under a path
`list_modules`	List modules declared in `settings.gradle(.kts)`
`list_variants`	List build variants of a module
`get_app_id`	Read the `applicationId` of a module
`show_gradle_config`	Show Gradle, AGP, Kotlin and version-catalog entries

Session defaults

Tool	Description
`session_set_defaults`	Set default project, module, variant, serial and appId for all later calls
`session_show_defaults`	Show the current defaults
`session_clear_defaults`	Clear all defaults, or only the listed keys

Build, test and quality

Tool	Description
`build_app`	Build an APK; returns compact `file:line` compiler errors
`build_run`	Build, install and launch in one call
`test_app`	Run JVM unit tests with a parsed pass/fail summary
`test_instrumented`	Run instrumented tests on a device
`lint`	Run Android Lint and summarize the report
`clean`	Run `gradle clean`
`get_apk_path`	Locate the most recent APK without building
`stop_gradle`	Stop the project's Gradle daemons
`get_coverage_report`	Run Kover/Jacoco and summarize line coverage per package
`get_file_coverage`	Show covered/uncovered lines of one source file

Devices and emulators

Tool	Description
`list_devices`	List devices with serial, state, model, Android version, API level
`list_avds`	List AVDs and which are running
`boot_emulator`	Boot an AVD and wait for full boot; returns the serial
`kill_emulator`	Shut down a running emulator
`create_avd`	Create an AVD from an installed system image
`delete_avd`	Delete an AVD
`set_emulator_location`	Set GPS location
`set_appearance`	Switch dark/light mode
`statusbar_demo_mode`	Clean status bar for screenshots

App lifecycle

Tool	Description
`install_app`	Install an APK (`adb install -r`)
`launch_app`	Launch by application id, resolving the launcher activity
`stop_app`	Force-stop a running app
`uninstall_app`	Uninstall an app
`clear_app_data`	Reset an app to fresh-install state
`get_app_info`	Version, target/min SDK, install path, running PID

UI automation

Tool	Description
`snapshot_ui`	Dump the UI as named elements with exact tap coordinates
`screenshot`	Capture the screen; `annotate: true` draws numbered boxes
`tap_element`	Tap element #N from the last annotated screenshot
`tap`	Tap at pixels or screen percentages
`scroll`	Scroll in a direction with a safe computed swipe
`swipe`	Swipe between two points
`drag`	Drag from one point to another
`long_press`	Long-press, holding 1000 ms
`type_text`	Type into the focused field, waiting for the keyboard
`key_press`	Press BACK, HOME, ENTER, DPAD_*, or any keycode
`key_sequence`	Press several keys in order
`wait_for_ui`	Poll until an element appears

Logs and recording

Tool	Description
`get_logs`	One-shot logcat dump, filterable by app and tag
`get_crash_logs`	Crash buffer: Java exceptions, native crashes, ANRs
`start_log_capture`	Start background logcat capture to a file
`stop_log_capture`	Stop capture and return the file plus the last lines
`record_video_start`	Start screen recording (max 3 minutes)
`record_video_stop`	Stop recording and pull the MP4

Scaffolding

Tool	Description
`scaffold_android_project`	Create a minimal Compose app that builds out of the box

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:

snapshot_ui — returns exact device-pixel centers for every named element. Preferred.
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.
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

Terminal

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.