{
  "markdown": "<div align=\"center\">\n<img src=\"assets/android-head_flat.svg\" width=\"72\" alt=\"Android robot logo\">\n\n# adb-mcp\n\n**An [MCP](https://modelcontextprotocol.io) server that drives Android emulators and devices over `adb`**\n\n[![Website](https://img.shields.io/badge/website-adb--mcp.com-3DDC84?logo=vercel&logoColor=white)](https://adb-mcp.com)\n[![Release](https://img.shields.io/github/v/release/iksnerd/adb-mcp?logo=github&color=3DDC84)](https://github.com/iksnerd/adb-mcp/releases/latest)\n[![CI](https://github.com/iksnerd/adb-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/iksnerd/adb-mcp/actions/workflows/ci.yml)\n[![Go](https://img.shields.io/badge/Go-1.26%2B-00ADD8?logo=go&logoColor=white)](go.mod)\n[![MCP](https://img.shields.io/badge/MCP-stdio-3DDC84)](https://modelcontextprotocol.io)\n\n</div>\n\n---\n\nBoot an AVD, screenshot, read the UI hierarchy, tap/swipe/type, set a device\nlock, read `logcat`, run Gradle builds and tests. [79 tools](docs/TOOLS.md),\nfrom Claude Code, Cursor, VS Code, or any MCP client over stdio.\n\nIt is the Android counterpart to [XcodeBuildMCP](https://github.com/getsentry/XcodeBuildMCP),\nbuilt on the official [Go MCP SDK](https://github.com/modelcontextprotocol/go-sdk).\n\n<div align=\"center\">\n<img src=\"assets/demo.gif\" width=\"600\" alt=\"An agent driving a real emulator with adb-mcp: describe_ui finds the Chrome icon, tap_on_text taps it, and a screenshot confirms Chrome launched. The emulator screen is shown side by side with the actual tool call and result.\">\n\n`describe_ui` → `tap_on_text` → `screenshot`, driven live against a real emulator (`emulator-5556`), showing the actual tool calls and their actual output.\n</div>\n\n> Android is a trademark of Google LLC. `adb-mcp` is an independent, unofficial\n> tool built for Android and is not affiliated with, sponsored, or endorsed by Google.\n> The Android robot above is reproduced/modified from work created and shared by\n> Google and used according to terms described in the\n> [Creative Commons 3.0 Attribution License](https://creativecommons.org/licenses/by/3.0/).\n\n## Why\n\nDriving Android by hand means a long runbook of raw `adb` commands, and it is\neasy to get wrong (stale tap coordinates, CRLF-corrupted screenshots, forgetting\n`exec-out`, guessing coordinates off a downscaled image). This server bakes\nthat knowledge into its tools, so the agent doesn't have to relearn it:\n\n- Screenshots use `exec-out screencap` (no CRLF corruption) and are auto-downscaled\n  so the image reader accepts them.\n- `describe_ui` returns each element's **center in true device pixels** (so taps\n  land where you mean them to, no guessing off the image) and retries the\n  transient \"could not get idle state\" failure on its own.\n\nThe workflow itself ships as readable **resources** the agent can pull up\nmid-task (the observe→act loop, native PIN/lock handling, crash triage, see\nbelow) instead of relearning them each session.\n\n## Getting started\n\n### 1. Prerequisites\n\n- Android SDK with `platform-tools` (`adb`) and `emulator`. The server finds it\n  via `$ANDROID_HOME` / `$ANDROID_SDK_ROOT`, else the platform default\n  (`~/Library/Android/sdk` on macOS). If your MCP client launches the server\n  without those set, pass `--sdk /path/to/sdk` in the client config's `args`\n  (the server then exports it, so Gradle finds the SDK too). `doctor` prints\n  the location it resolved.\n- At least one AVD (create one in Android Studio's Device Manager).\n\nGo is **not** required: releases ship prebuilt binaries, and it's only needed to\n[build from source](#from-source-go-126).\n\n### 2. Install\n\nOn macOS/Linux:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/iksnerd/adb-mcp/main/install.sh | sh\n```\n\nThe script ([install.sh](install.sh)) picks the right archive for your\nOS/architecture, verifies its SHA-256 against the release's `checksums.txt`,\nand installs to `~/.local/bin` (override with `BIN_DIR=...`; pin a version\nwith `VERSION=v0.17.0`).\n\nPrefer to grab the binary yourself? Every platform's archive (macOS, Linux,\nand Windows, amd64 and arm64) is on the\n[Releases page](https://github.com/iksnerd/adb-mcp/releases/latest), each with a\nchecksum in `checksums.txt`. On Windows, download the `windows_amd64` or\n`windows_arm64` zip and put `adb-mcp.exe` somewhere on your `PATH`.\n\nOnce installed, stay current with the built-in updater. It fetches the latest\nrelease, verifies its checksum, and swaps the binary in place:\n\n```bash\nadb-mcp update\n```\n\nThe registration below launches the server by the bare name `adb-mcp`, so it\nmust be on your `$PATH` (`which adb-mcp` should resolve; the installer warns\nif `~/.local/bin` isn't on it). Otherwise point the client at the absolute\npath to the binary instead.\n\n### 3. Register with your MCP client\n\n**Claude Code:**\n\n```bash\nclaude mcp add adb -- adb-mcp\n```\n\n(When working inside this repo itself, the bundled `.mcp.json` is picked up\nautomatically, no registration needed.)\n\nOr install as a **plugin**, which registers the server and adds a skill per\ndriving guide:\n\n```bash\nclaude plugin marketplace add iksnerd/adb-mcp\nclaude plugin install adb-mcp@adb-mcp\n```\n\nFor Codex, the same plugin ships in Codex's manifest shape:\n\n```bash\ncodex plugin marketplace add iksnerd/adb-mcp\ncodex plugin add adb-mcp@adb-mcp-plugins\n```\n\nEither way `adb-mcp` still has to be on your `PATH` from step 2 - the plugin\nregisters the server, it does not install the binary.\n\n**Cursor / VS Code**: one-click install (assumes `adb-mcp` is on your `PATH`\nfrom step 2):\n\n[<img src=\"https://cursor.com/deeplink/mcp-install-dark.svg\" alt=\"Install in Cursor\" height=\"20\">](https://cursor.com/en/install-mcp?name=adb&config=eyJjb21tYW5kIjoiYWRiLW1jcCJ9)\n[<img src=\"https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square\" alt=\"Install in VS Code\" height=\"20\">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522adb%2522%252C%2522command%2522%253A%2522adb-mcp%2522%257D)\n\n**Any other client** (Windsurf, Codex, …): run `adb-mcp` over stdio.\nThe usual config shape:\n\n```json\n{\n  \"mcpServers\": {\n    \"adb\": { \"command\": \"adb-mcp\" }\n  }\n}\n```\n\nTo confirm it's wired up, ask your agent to \"boot an emulator and take a screenshot\".\n\n### From source (Go 1.26+)\n\n```bash\nmake install                 # builds ./bin/adb-mcp and copies it to ~/.local/bin\n# or:\ngo build -o bin/adb-mcp ./cmd/adb-mcp\n# or straight from the module (note the /cmd/adb-mcp suffix):\ngo install github.com/iksnerd/adb-mcp/cmd/adb-mcp@latest\n```\n\n## Tools\n\n79 tools across ten areas. Every device-facing tool takes an optional\n`serial` (adb `-s`). Omit it with one device attached, or pass one from\n`list_devices` with several. Full reference: [docs/TOOLS.md](docs/TOOLS.md).\n\n- **Emulator / device**: boot, list, wait-for-boot, shut down, connect over Wi-Fi, `adb_reverse` port forwarding (Metro!)\n- **Observe**: `screenshot` to see (works on multi-display foldables, pick a panel with `display`), `describe_ui` for true-pixel element centers, with the focused **top window** (spot a biometric prompt, or the wrong app entirely, occluding your target via optional `package`), `filter`/`query`/`compact` modes, and a hidden-node count so absence is trustworthy\n- **Interact**: tap, `tap_on_text`/`tap_element` (id-addressed), swipe, drag, long-press, type, key combos, PIN pads, `wait`, `run_sequence` (batch steps + guards in one call, which keeps native-timer flows from being perturbed by per-step round-trips); opt-in `verify_change` tells you whether a tap/key actually changed the UI; opt-in `via_accessibility` on `tap_on_text`/`tap_element` (EXPERIMENTAL) dispatches a real accessibility click for native views a coordinate tap can't reach, see [bridge/README.md](bridge/README.md)\n- **Lock / Keystore / Biometrics**: set/clear a secure lock screen, check lock state, `has_biometric_enrolled` + `fingerprint_touch`/`finger_remove` to satisfy a BiometricPrompt on the emulator\n- **Extended Controls (emulator)**: `send_sms` (OTP/2FA), `phone_call`, `set_battery` (also works on real devices via dumpsys), `cellular` (roaming/weak-signal/throttled), `set_sensor` (accelerometer/light/…), `rotate_screen`, `avd_snapshot`, driving the emulator's console-only panel that `describe_ui` can't see\n- **App lifecycle**: install/uninstall, launch/stop, `app_state` (running pid(s) + Metro-vs-embedded bundle), `launch_dev_client` (Expo dev build → Metro, skipping the Dev Launcher), `reload_app`/`open_dev_menu`, clear data, permissions, deep links, push/pull files, `last_crash`\n- **Logs & capture**: one-shot or streaming `logcat` (substring/priority/tag filters, `since` time window, opt-in `redact` to mask tokens/passwords/API keys before output), `clear_logcat`, `last_crash`, screen recording\n- **Environment & diagnostics**: dark mode, mock location, clean status bar, `stay_awake` (stop a doze-happy screen blanking your screenshots), `doctor`\n- **Gradle build & test**: `assembleDebug`, unit tests, instrumented tests, JVM unit-test coverage via JaCoCo (`get_coverage_report`/`get_file_coverage`), task + variant + module discovery (`list_gradle_variants`/`list_gradle_projects`), one-shot `build_and_run`\n- **Session defaults**: pin `project_dir`/`serial` once (`session_set_defaults`) so a multi-module/multi-flavor project or multi-device session doesn't need them repeated on every call\n\nThe driving know-how itself ships as six MCP **resources** (`android://guide/*`)\nthe client can list and read. See [docs/TOOLS.md](docs/TOOLS.md) for the URIs,\nor jump straight to `android://guide/driving` for the core loop below.\n\n## The core loop\n\n**observe → locate → act → re-observe.** `screenshot` to see, `describe_ui` to\nget true-pixel centers, `tap`/`tap_on_text`/`swipe`/`input_text` to act, then\n`screenshot` again to confirm. Read `android://guide/driving` for the full loop\nand the gotchas that waste turns.\n\n## Development\n\n```bash\nmake check     # go vet + go test (unit tests need no emulator)\nmake run       # run over stdio for manual JSON-RPC poking\n```\n\nLayout:\n\n```\ncmd/adb-mcp/main.go        entry: subcommands (update/version) or serve MCP over stdio\ninternal/tools/            thin MCP tool bindings\ninternal/adb/              the device layer: an adb.Client whose methods are the commands\ninternal/gradle/           host-side Gradle: build, find APKs, parse test reports\ninternal/uiauto/           pure uiautomator-hierarchy model + parsing (unit-tested)\ninternal/sdk/              resolves the Android SDK (adb/emulator paths, PATH env)\ninternal/concurrent/       RunAll/RunIndexed: fan out independent I/O calls, join, done\ninternal/guides/           the skill guides, embedded and served as MCP resources\ninternal/selfupdate/       the `adb-mcp update` release fetch/verify/swap\ninternal/bridgeupdate/     the `adb-mcp bridge install` release fetch/verify/install\n```\n\nDependencies point inward only (`tools → adb, gradle, uiauto → sdk`), and each\n`internal/tools/<domain>.go` adapter **mirrors** an execution file of the same\nname (device commands are `adb.Client` methods). Full map, the package graph,\nand the rules for adding a tool: [ARCHITECTURE.md](ARCHITECTURE.md).\n\n## Documentation\n\n- [adb-mcp.com](https://adb-mcp.com): landing page\n- [docs/TOOLS.md](docs/TOOLS.md): full tool-by-tool reference and the guide resources\n- [ARCHITECTURE.md](ARCHITECTURE.md): the mirror convention, package layout, and how to add a tool\n- [docs/CHANGELOG.md](docs/CHANGELOG.md): shipped work, newest first\n- [docs/BACKLOG.md](docs/BACKLOG.md): open ideas and XcodeBuildMCP parity gaps\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup and conventions. Found a\nsecurity issue? See [SECURITY.md](SECURITY.md) instead of opening a public\nissue. Licensed under [MIT](LICENSE).\n",
  "bytes": 11762,
  "sha": "391b7b9d3e714c0590b7f6b80e294c12868fd650db6f99d2f5e10f6dc04818c3",
  "repo_slug": "iksnerd/adb-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_iksnerd_adb_mcp_4829db87/readme"
}