{
  "markdown": "# AndroidBuildMCP\n\n[![npm](https://img.shields.io/npm/v/@asjackson/androidbuild-mcp)](https://www.npmjs.com/package/@asjackson/androidbuild-mcp)\n[![license](https://img.shields.io/npm/l/@asjackson/androidbuild-mcp)](LICENSE)\n\nGive 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.\n\n## Quick start\n\nRequirements: Node 18+, the Android SDK (`ANDROID_HOME` or a default install), and a JDK 17+ for Gradle builds.\n\nNo install step — `npx` fetches the server on first run.\n\n**Claude Code**\n\n```bash\nclaude mcp add androidbuild -- npx -y @asjackson/androidbuild-mcp\n```\n\n**Any other MCP client**\n\n```json\n{\n  \"mcpServers\": {\n    \"androidbuild\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@asjackson/androidbuild-mcp\"]\n    }\n  }\n}\n```\n\n<details>\n<summary>Run from source instead</summary>\n\n```bash\ngit clone https://github.com/dev-jackson/androidbuild-mcp.git\ncd androidbuild-mcp\nnpm install && npm run build\nclaude mcp add androidbuild -- node /absolute/path/to/androidbuild-mcp/dist/index.js\n```\n\n</details>\n\nThen ask your agent to run `doctor` — it checks the SDK, adb, emulator, Java and connected devices, and tells you exactly what is missing.\n\n## What your agent can do\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **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.\n- **Read the logs** — background logcat capture filtered to your app, one-shot dumps, and the crash buffer for stack traces.\n- **Start new apps** — `scaffold_android_project` generates a minimal Compose project that builds out of the box.\n\nSession defaults (`session_set_defaults`) mean you configure project, module, variant and device once — every other call then works without arguments.\n\n## Tool reference\n\n53 tools over stdio. Every tool takes plain arguments and returns text (or an image, for `screenshot`).\n\n**Environment and project**\n\n| Tool | Description |\n| --- | --- |\n| `doctor` | Check SDK, adb, emulator, avdmanager, Java and connected devices; reports what is missing |\n| `discover_projects` | Find Android/Gradle projects under a path |\n| `list_modules` | List modules declared in `settings.gradle(.kts)` |\n| `list_variants` | List build variants of a module |\n| `get_app_id` | Read the `applicationId` of a module |\n| `show_gradle_config` | Show Gradle, AGP, Kotlin and version-catalog entries |\n\n**Session defaults**\n\n| Tool | Description |\n| --- | --- |\n| `session_set_defaults` | Set default project, module, variant, serial and appId for all later calls |\n| `session_show_defaults` | Show the current defaults |\n| `session_clear_defaults` | Clear all defaults, or only the listed keys |\n\n**Build, test and quality**\n\n| Tool | Description |\n| --- | --- |\n| `build_app` | Build an APK; returns compact `file:line` compiler errors |\n| `build_run` | Build, install and launch in one call |\n| `test_app` | Run JVM unit tests with a parsed pass/fail summary |\n| `test_instrumented` | Run instrumented tests on a device |\n| `lint` | Run Android Lint and summarize the report |\n| `clean` | Run `gradle clean` |\n| `get_apk_path` | Locate the most recent APK without building |\n| `stop_gradle` | Stop the project's Gradle daemons |\n| `get_coverage_report` | Run Kover/Jacoco and summarize line coverage per package |\n| `get_file_coverage` | Show covered/uncovered lines of one source file |\n\n**Devices and emulators**\n\n| Tool | Description |\n| --- | --- |\n| `list_devices` | List devices with serial, state, model, Android version, API level |\n| `list_avds` | List AVDs and which are running |\n| `boot_emulator` | Boot an AVD and wait for full boot; returns the serial |\n| `kill_emulator` | Shut down a running emulator |\n| `create_avd` | Create an AVD from an installed system image |\n| `delete_avd` | Delete an AVD |\n| `set_emulator_location` | Set GPS location |\n| `set_appearance` | Switch dark/light mode |\n| `statusbar_demo_mode` | Clean status bar for screenshots |\n\n**App lifecycle**\n\n| Tool | Description |\n| --- | --- |\n| `install_app` | Install an APK (`adb install -r`) |\n| `launch_app` | Launch by application id, resolving the launcher activity |\n| `stop_app` | Force-stop a running app |\n| `uninstall_app` | Uninstall an app |\n| `clear_app_data` | Reset an app to fresh-install state |\n| `get_app_info` | Version, target/min SDK, install path, running PID |\n\n**UI automation**\n\n| Tool | Description |\n| --- | --- |\n| `snapshot_ui` | Dump the UI as named elements with exact tap coordinates |\n| `screenshot` | Capture the screen; `annotate: true` draws numbered boxes |\n| `tap_element` | Tap element #N from the last annotated screenshot |\n| `tap` | Tap at pixels or screen percentages |\n| `scroll` | Scroll in a direction with a safe computed swipe |\n| `swipe` | Swipe between two points |\n| `drag` | Drag from one point to another |\n| `long_press` | Long-press, holding 1000 ms |\n| `type_text` | Type into the focused field, waiting for the keyboard |\n| `key_press` | Press BACK, HOME, ENTER, DPAD_*, or any keycode |\n| `key_sequence` | Press several keys in order |\n| `wait_for_ui` | Poll until an element appears |\n\n**Logs and recording**\n\n| Tool | Description |\n| --- | --- |\n| `get_logs` | One-shot logcat dump, filterable by app and tag |\n| `get_crash_logs` | Crash buffer: Java exceptions, native crashes, ANRs |\n| `start_log_capture` | Start background logcat capture to a file |\n| `stop_log_capture` | Stop capture and return the file plus the last lines |\n| `record_video_start` | Start screen recording (max 3 minutes) |\n| `record_video_stop` | Stop recording and pull the MP4 |\n\n**Scaffolding**\n\n| Tool | Description |\n| --- | --- |\n| `scaffold_android_project` | Create a minimal Compose app that builds out of the box |\n\n## Tapping accurately\n\nEverything 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:\n\n1. **`snapshot_ui`** — returns exact device-pixel centers for every named element. Preferred.\n2. **`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.\n3. **`tap { xPct, yPct }`** — screen percentages (0-1), also available on long_press/swipe/drag. Resolution-independent.\n\nRaw `tap { x, y }` still works when you have real pixel coordinates.\n\n## Reliability\n\nEvery 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:\n\n- `type_text` waits for the soft keyboard before injecting (typing right after focusing a field silently drops the first characters otherwise).\n- `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.\n- Taps outside the screen are rejected with the actual screen size instead of silently doing nothing.\n- Text-heavy screens (e-book WebViews and the like) are capped and searchable with `snapshot_ui { filter }` instead of flooding the context.\n- Build/test/device failures come back as short, actionable messages with the next tool to call.\n\n## Optional extras\n\n- [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.\n- 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.\n\n## Development\n\n```bash\nnpm install\nnpm test            # unit tests (no real processes spawned)\nnpm run dev         # run the server from source\nnpm run build       # compile to dist/\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nConceptually inspired by [XcodeBuildMCP](https://github.com/getsentry/XcodeBuildMCP); independent implementation built around the Android toolchain.\n",
  "bytes": 9303,
  "sha": "ebde1f8cbfcf5955bf123f8471f83ff37281b5419ede1cda1c87e339de091b48",
  "repo_slug": "dev-jackson/androidbuild-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dev_jackson_androidbuild_mcp_e17e1cca/readme"
}