androidbuild-mcp

# AndroidBuildMCP

[![npm](https://img.shields.io/npm/v/@asjackson/androidbuild-mcp)](https://www.npmjs.com/package/@asjackson/androidbuild-mcp)
[![license](https://img.shields.io/npm/l/@asjackson/androidbuild-mcp)](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**

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

**Any other MCP client**

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

<details>
<summary>Run from source instead</summary>

```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
```

</details>

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:

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](https://github.com/dev-jackson/androidbuild-mcp/blob/main/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](https://developer.android.com/tools/agents/android-cli) enables `screenshot { annotate: true }`. `doctor` prints the one-line installer for your OS.
- The [ADBKeyboard IME](https://github.com/senzhk/ADBKeyBoard) enables non-ASCII `type_text` (adb alone is ASCII-only). Install its APK once; the server uses it automatically.

## Development

```bash
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](LICENSE).

Conceptually inspired by [XcodeBuildMCP](https://github.com/getsentry/XcodeBuildMCP); independent implementation built around the Android toolchain.