{"_id":"@asjackson/androidbuild-mcp","_rev":"2-5349c441993c920f8b9148a37aeffe3f","name":"@asjackson/androidbuild-mcp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@asjackson/androidbuild-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","android","gradle","adb","emulator","agent"],"author":{"url":"https://github.com/dev-jackson","name":"Jackson"},"license":"MIT","_id":"@asjackson/androidbuild-mcp@0.1.0","maintainers":[{"name":"asjackson","email":"angeljackson0933@gmail.com"}],"homepage":"https://github.com/dev-jackson/androidbuild-mcp#readme","bugs":{"url":"https://github.com/dev-jackson/androidbuild-mcp/issues"},"bin":{"androidbuild-mcp":"dist/index.js"},"dist":{"shasum":"5aee7e82de766c19ea3f1a1bf42363edb790c9c9","tarball":"https://registry.npmjs.org/@asjackson/androidbuild-mcp/-/androidbuild-mcp-0.1.0.tgz","fileCount":38,"integrity":"sha512-HBaDC5GlsXxc0CvRNh07jbYmqlSRf26+AtCpQip5njg7EX1Hrdh/C7saPxeHDCwSbHZLPxlNTRdfT1/m2mzKZQ==","signatures":[{"sig":"MEYCIQCSN26O/qi0OJ/StSKqHH70UzjqN/ls90uxJ3txz7pskwIhALWlN+UhcdZSM3hv3O7fJwN0k1OTn5icwvxEvOcieaVk","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":191380},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"18e996fb14ad1a915cd3dbd7a8fa78a8bfb9bccd","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc -p tsconfig.build.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"asjackson","email":"angeljackson0933@gmail.com"},"repository":{"url":"git+https://github.com/dev-jackson/androidbuild-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"MCP server exposing Android development tools (Gradle builds, emulators, adb, logcat, UI automation) to AI agents","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^3.25.76","execa":"^9.6.1","fast-xml-parser":"^5.2.5","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.2.0","typescript":"^5.8.0","@types/node":"^22.15.0"},"_npmOperationalInternal":{"tmp":"tmp/androidbuild-mcp_0.1.0_1785254958618_0.7090868185572583","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@asjackson/androidbuild-mcp","version":"0.1.1","mcpName":"io.github.dev-jackson/androidbuild-mcp","description":"MCP server to build, deploy, drive and debug Android apps: Gradle, emulators, adb, logcat, UI automation","license":"MIT","author":{"name":"Jackson","url":"https://github.com/dev-jackson"},"repository":{"type":"git","url":"git+https://github.com/dev-jackson/androidbuild-mcp.git"},"bugs":{"url":"https://github.com/dev-jackson/androidbuild-mcp/issues"},"homepage":"https://github.com/dev-jackson/androidbuild-mcp#readme","type":"module","bin":{"androidbuild-mcp":"dist/index.js"},"main":"dist/index.js","engines":{"node":">=18"},"scripts":{"build":"tsc -p tsconfig.build.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"","dev":"tsx src/index.ts","test":"vitest run","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["mcp","mcp-server","model-context-protocol","android","gradle","adb","emulator","agent","logcat","ui-automation","android-testing","jetpack-compose","apk","claude","cursor"],"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","execa":"^9.6.1","fast-xml-parser":"^5.2.5","zod":"^3.25.76"},"devDependencies":{"@types/node":"^22.15.0","tsx":"^4.19.0","typescript":"^5.8.0","vitest":"^3.2.0"},"_id":"@asjackson/androidbuild-mcp@0.1.1","gitHead":"98055b2db74f4384f99b43100f7e1ca40efb022e","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-fsc/d0oO2kaKnWBf4QGJR1hmyHbI4dAjbzAjI0gS36roHEEtrpapiWmqiqJVf/0voq8sGEBuyD5ZaESiHcL4xQ==","shasum":"1748506c934fed429b1a9162b75df37c9dc3d09b","tarball":"https://registry.npmjs.org/@asjackson/androidbuild-mcp/-/androidbuild-mcp-0.1.1.tgz","fileCount":38,"unpackedSize":195742,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHFj6352Fy4CR7iKe2ZenJgYMJbAkiJmj6JUPldGff1SAiA+vSKER/uuWiOfLHJ+djqtyrmBhfAtgqF/3E3ER/wlJw=="}]},"_npmUser":{"name":"asjackson","email":"angeljackson0933@gmail.com"},"directories":{},"maintainers":[{"name":"asjackson","email":"angeljackson0933@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/androidbuild-mcp_0.1.1_1785255380104_0.8966921680328424"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T16:09:18.443Z","modified":"2026-07-28T16:16:20.445Z","0.1.0":"2026-07-28T16:09:18.786Z","0.1.1":"2026-07-28T16:16:20.281Z"},"bugs":{"url":"https://github.com/dev-jackson/androidbuild-mcp/issues"},"author":{"name":"Jackson","url":"https://github.com/dev-jackson"},"license":"MIT","homepage":"https://github.com/dev-jackson/androidbuild-mcp#readme","keywords":["mcp","mcp-server","model-context-protocol","android","gradle","adb","emulator","agent","logcat","ui-automation","android-testing","jetpack-compose","apk","claude","cursor"],"repository":{"type":"git","url":"git+https://github.com/dev-jackson/androidbuild-mcp.git"},"description":"MCP server to build, deploy, drive and debug Android apps: Gradle, emulators, adb, logcat, UI automation","maintainers":[{"name":"asjackson","email":"angeljackson0933@gmail.com"}],"readme":"# 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","readmeFilename":"README.md"}