Skip to main content
Glama

AndroidBuildMCP

npm license

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"]
    }
  }
}
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.

Related MCP server: Android DevTools MCP

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:

  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.

Available Tools

53 tools
boot_emulatorBoot emulatorA

Boot an AVD in the background and wait until Android finishes booting. Returns the adb serial. Set wipeData to factory-reset the AVD on boot.

Inputs: avdName (required), wipeData, timeoutSeconds.

build_appBuild appA

Build an APK with Gradle (assemble). On failure returns compact compiler errors with file:line. On success returns the APK path.

Inputs: module, variant, projectDir.

build_runBuild, install and runA

Build the APK, install it on a device/emulator (adb install -r), and launch the app. Needs appId (session default or argument) to launch.

Inputs: appId, module, serial, variant, +1 more.

cleanClean buildB

Run gradle clean for the project.

Inputs: projectDir.

clear_app_dataClear app dataA

Clear all data of an app (pm clear) — resets it to a fresh-install state.

Inputs: appId, serial.

create_avdCreate AVDA

Create an AVD from an installed system image (e.g. 'system-images;android-35;google_apis;arm64-v8a'). If systemImage is omitted, lists the installed images to choose from.

Inputs: name (required), device, systemImage.

delete_avdDelete AVDB

Delete an AVD permanently.

Inputs: name (required).

discover_projectsDiscover Gradle projectsA
Read-only

Find Android/Gradle projects (directories with settings.gradle[.kts]) under a path. Use the result to session_set_defaults projectDir.

Inputs: searchPath (required), maxDepth.

doctorDoctorA
Read-only

Check the Android development environment: SDK location, adb, emulator, avdmanager, Java, and connected devices. Run this first if any other tool fails with a missing-binary error.

Inputs: no named parameters.

dragDrag and dropB
Read-only

Drag an element from one point to another (input draganddrop). Instead of pixels you can pass screen percentages (0-1): safer when estimating positions from a screenshot image.

Inputs: x1, x2, y1, y2, +6 more.

get_apk_pathGet APK pathA
Read-only

Locate the most recent built APK for a module/variant without building.

Inputs: module, variant, projectDir.

get_app_idGet application idA
Read-only

Get the applicationId (package name) of a module, parsed from its build.gradle(.kts). Needed by install/launch/log tools.

Inputs: module, variant, projectDir.

get_app_infoGet app infoA
Read-only

Get installed-app info from the device: version, target/min SDK, install path, running PID.

Inputs: appId, serial.

get_coverage_reportGet coverage reportA

Run a coverage Gradle task (Kover or Jacoco) and summarize line coverage per package. Tries koverXmlReport by default; pass 'task' for a custom one (e.g. jacocoTestReport). The project must apply a coverage plugin.

Inputs: task, module, skipRun, projectDir.

get_crash_logsGet crash logsA
Read-only

Dump the crash log buffer (Java exceptions, native crashes, ANRs).

Inputs: lines, serial.

get_file_coverageGet file coverageA
Read-only

Show covered/uncovered line numbers of one source file from the latest coverage report (run get_coverage_report first).

Inputs: file (required), module, projectDir.

get_logsGet recent logsA
Read-only

One-shot dump of recent logcat lines, optionally filtered by app (must be running) and/or tag.

Inputs: tag, appId, lines, serial.

install_appInstall appA

Install an APK on a device/emulator (adb install -r).

Inputs: apkPath (required), serial.

key_pressPress keyA
Read-only

Press a hardware/navigation key: BACK, HOME, ENTER, TAB, DELETE, ESCAPE, MENU, APP_SWITCH, DPAD_*, or any KEYCODE_ name.

Inputs: key (required), serial.

key_sequencePress key sequenceA
Read-only

Press several keys in order (same names as key_press).

Inputs: keys (required), serial.

kill_emulatorKill emulatorA

Shut down a running emulator (adb emu kill).

Inputs: serial.

launch_appLaunch appA

Launch an app by application id (resolves the launcher activity automatically).

Inputs: appId, serial.

lintRun Android LintB

Run Android Lint (lint) and return the textual report summary.

Inputs: module, variant, projectDir.

list_avdsList AVDsA
Read-only

List available Android Virtual Devices and which ones are currently running.

Inputs: no named parameters.

list_devicesList devicesA
Read-only

List connected devices and emulators with serial, state, model, Android version and API level.

Inputs: no named parameters.

list_modulesList Gradle modulesA
Read-only

List modules declared in settings.gradle(.kts) of the project.

Inputs: projectDir.

list_variantsList build variantsA
Read-only

List build variants of a module by inspecting its Gradle assemble tasks (runs './gradlew :tasks').

Inputs: module, projectDir.

long_pressLong pressA
Read-only

Long-press the screen at coordinates. Instead of pixels you can pass screen percentages (0-1): safer when estimating positions from a screenshot image.

Inputs: x, y, xPct, yPct, +2 more.

record_video_startStart screen recordingA

Start recording the device screen (adb screenrecord, max 3 minutes). Returns a recordingId for record_video_stop.

Inputs: serial, timeLimitSeconds.

record_video_stopStop screen recordingA

Stop a screen recording and pull the MP4 to the local machine.

Inputs: recordingId (required).

scaffold_android_projectScaffold Android projectA

Create a new minimal Jetpack Compose app project (single module, version catalog, Gradle wrapper included) ready to build with build_app.

Inputs: appName (required), directory (required), packageName (required).

screenshotScreenshotA
Read-only

Take a screenshot of the device/emulator screen and return it as an image. With annotate: true (needs the Google android CLI), UI elements get numbered bounding boxes — including text inside images/WebViews that snapshot_ui cannot see.

Inputs: serial, annotate.

scrollScrollA
Read-only

Scroll the screen in a direction (computes a safe swipe in the middle of the screen, avoiding the status bar and navigation areas). Prefer this over raw swipe for scrolling.

Inputs: direction (required), amount, serial.

session_clear_defaultsClear session defaultsB
Read-only

Clear all session defaults, or only the listed keys.

Inputs: keys.

session_set_defaultsSet session defaultsA
Read-only

Set default projectDir/module/variant/serial/appId used by other tools when the corresponding argument is omitted. Set these once after discovering the project.

Inputs: appId, module, serial, variant, +1 more.

session_show_defaultsShow session defaultsA
Read-only

Show the current session defaults.

Inputs: no named parameters.

set_appearanceSet dark/light modeA

Switch a device/emulator between dark and light mode (cmd uimode night).

Inputs: mode (required), serial.

set_emulator_locationSet emulator locationB

Set the GPS location of a running emulator.

Inputs: latitude (required), longitude (required), serial.

show_gradle_configShow Gradle configA
Read-only

Show toolchain versions: Gradle (from wrapper properties) and everything in the version catalog (AGP, Kotlin, Compose, ...).

Inputs: projectDir.

snapshot_uiSnapshot UI hierarchyA
Read-only

Dump the current UI as a compact list of actionable elements (text, id, content-desc, tap coordinates). Use the @(x,y) centers with tap/long_press. Text-heavy screens are capped; pass 'filter' to search within them.

Inputs: filter, serial.

start_log_captureStart log captureA

Start capturing logcat to a file in the background. Filter by app (via its pid) and/or tag. Returns a sessionId for stop_log_capture. The app must be running to filter by appId.

Inputs: tag, appId, clear, serial.

statusbar_demo_modeStatus bar demo modeA

Enable clean status bar for screenshots (fixed clock, full battery, full signal) or disable it.

Inputs: enabled (required), clock, serial.

stop_appStop appA

Force-stop a running app (am force-stop).

Inputs: appId, serial.

stop_gradleStop Gradle daemonsA

Stop the project's Gradle daemons (use when a build hangs or to free memory).

Inputs: projectDir.

stop_log_captureStop log captureA

Stop a log capture session and return the file path plus the last lines.

Inputs: sessionId (required), tailLines.

swipeSwipeA
Read-only

Swipe from one point to another (scrolling, dismissing). For drag-and-drop use drag instead. Instead of pixels you can pass screen percentages (0-1): safer when estimating positions from a screenshot image.

Inputs: x1, x2, y1, y2, +6 more.

tapTapA
Read-only

Tap the screen. Coordinates from snapshot_ui are exact device pixels — prefer them over estimating positions by looking at a screenshot image. Instead of pixels you can pass screen percentages (0-1): safer when estimating positions from a screenshot image.

Inputs: x, y, xPct, yPct, +1 more.

tap_elementTap annotated elementA
Read-only

Tap element #N from the most recent screenshot { annotate: true } capture — no coordinate math needed. The mapping is exact even if your client displays the image scaled. Re-capture after the UI changes: element numbers go stale.

Inputs: element (required), serial.

test_appRun unit testsA

Run local JVM unit tests (testUnitTest) and return a parsed pass/fail summary with failure messages.

Inputs: tests, module, variant, projectDir.

test_instrumentedRun instrumented testsB

Run instrumented tests on a connected device/emulator (connectedAndroidTest) and return a parsed summary. Requires a booted device.

Inputs: module, variant, projectDir.

type_textType textA
Read-only

Type ASCII text into the focused field. Waits for the soft keyboard first, so it is safe to call right after tapping a field. Options: clear the field first, press ENTER after. Non-ASCII characters are not supported by adb input.

Inputs: text (required), clear, serial, submit.

uninstall_appUninstall appB

Uninstall an app from a device/emulator.

Inputs: appId, serial.

wait_for_uiWait for UIA
Read-only

Poll the UI until an element containing the given text / content-desc / resource-id appears. Returns its tap coordinates.

Inputs: match (required), serial, timeoutSeconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 53 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes (build, device, UI, logging). A few pairs like snapshot_ui and screenshot with annotate could be confused, but descriptions clarify their complementary roles. Overall, the tool set is well-separated into functional areas.

    Naming Consistency5/5

    Tools overwhelmingly follow a verb_noun snake_case pattern (build_app, list_devices, start_log_capture). Minor exceptions like statusbar_demo_mode and session_set_defaults are still intuitive and consistent in style. No mixing of camelCase or arbitrary names.

    Tool Count2/5

    53 tools is excessive given the rule that 25+ is too many. While the scope is broad and each tool has a purpose, the sheer number creates navigation overhead and can overwhelm an agent. A more consolidated set would be better.

    Completeness5/5

    The tool surface thoroughly covers the Android development lifecycle: project discovery, building, testing, linting, device/emulator management, UI automation, logging, coverage, and scaffolding. There are no major dead ends or obvious missing operations for the stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to control Android devices and emulators through direct UI interaction, allowing app navigation, automated testing, and real-world task execution via ADB without computer vision or scripts.
      18
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables an agent to inspect and interact with Android emulators or physical devices via ADB, capturing UI snapshots, tapping nodes, typing text, and reading app logs.
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to build, drive, and observe Android/KMM apps end-to-end through ADB and Gradle, with tools for UI automation, error capture, and testing.
      33
      43 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and IDEs to drive real Android devices and emulators for cross-app UI automation, testing, and diagnostics, including collecting Logcat output and screenshots.
      Apache 2.0