adbmcp — Android Debug Bridge, as MCP tools

adbmcp is a Model Context Protocol server that exposes the Android Debug Bridge (adb) to AI agents: list devices, run shell commands, install apps, read logcat, take screenshots, drive the UI (tap/swipe/type/key events), query system services with dumpsys, transfer files, forward ports, manage app permissions and pair/connect to devices over Wi-Fi. It is a thin, predictable wrapper around the official adb binary — no re-implemented adb protocol, no test framework, no extra state.

• Multi-device first — every device-scoped tool takes an optional device serial and every adb call is scoped with adb -s ; ambiguity is an error listing the candidates.
• Failures an agent can act on — adb stderr/exit codes are mapped to typed causes (NO_DEVICE, MULTIPLE_DEVICES, DEVICE_UNAUTHORIZED, DEVICE_OFFLINE, ADB_SERVER_CONFLICT, TIMEOUT, COMMAND_FAILED) with a hint for the next step.
• Safety by construction — full MCP annotations on every tool plus server-side guardrails that are enforced even if a host ignores annotations.
• stdio by default, Streamable HTTP optional — the client launches adbmcp as a subprocess; --http serves the same tools over /mcp for shared-device-host deployments.

Implements the MVP plus v2.0 items 1–7 in docs/design/product-design-v0.md.

Install

Requires Node.js >= 20 and Android platform-tools (adb) on PATH — or ADB_PATH pointing at the binary.

# from npm
npx -y @yhuangsh/adbmcp

# from a checkout
git clone https://github.com/yhuangsh/adbmcp.git && cd adbmcp
npm install
npm run build
node dist/index.js        # speaks MCP on stdin/stdout

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "adb": {
      "command": "npx",
      "args": ["-y", "adbmcp"],
      "env": {
        "ADB_PATH": "/Users/me/Library/Android/sdk/platform-tools/adb"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "adb": {
      "command": "node",
      "args": ["/absolute/path/to/adbmcp/dist/index.js"],
      "env": {
        "ADBMCP_ALLOWED_DEVICES": "emulator-5554"
      }
    }
  }
}

Other stdio clients work the same way: a command plus args, with ADB_PATH / ADBMCP_* environment variables passed through. In stdio mode, stdout carries MCP protocol traffic only; diagnostics go to stderr.

Streamable HTTP (shared device host)

Use HTTP when several agents or MCP clients should share one machine’s adb server, devices and allowlist — an emulator farm, a lab phone, or a remote desktop — instead of each client launching its own subprocess. stdio stays the default: with no flags, adbmcp speaks MCP on stdin/stdout.

node dist/index.js --http                                    # http://127.0.0.1:3331/mcp
ADBMCP_HTTP_TOKEN=secret node dist/index.js --http --host 0.0.0.0 --port 8080

The endpoint is stateful: initialize creates a session, Mcp-Session-Id identifies it, and DELETE /mcp closes it. All sessions share one device host, one ADBMCP_ALLOWED_DEVICES allowlist and one logcat stream registry — streams started in one session can be read from another. Sessions are the same trust domain, not isolation between agents.

Client config (Claude Desktop, Cursor, or any Streamable HTTP client):

{
  "mcpServers": {
    "adb": {
      "type": "http",
      "url": "http://localhost:3331/mcp"
    }
  }
}

When ADBMCP_HTTP_TOKEN is set, add "headers": { "Authorization": "Bearer " } to the server entry (client support for header config varies).

Security notes:

• Loopback by default. Binding a non-loopback host without ADBMCP_HTTP_TOKEN is refused at startup; the error explains the two ways forward (set a token, or bind 127.0.0.1).
• Token auth is pre-MCP. With a token configured, missing/incorrect credentials get 401 before any MCP session handling; comparison is constant-time (node:crypto timingSafeEqual).
• DNS-rebinding protection. The SDK transport rejects requests whose Host header is not the bound host or a loopback alias (localhost, 127.0.0.1, ::1) on the actual port. Override with ADBMCP_HTTP_ALLOWED_HOSTS when a reverse proxy forwards a different hostname.
• One device host, many agents. shell is available to every session; on a shared host prefer ADBMCP_ALLOWED_DEVICES and ADBMCP_SHELL_ALLOWED_PREFIXES, and put the server behind the token.
• No in-process TLS. The server speaks plain HTTP; terminate TLS in a reverse proxy for non-loopback deployments and set ADBMCP_HTTP_ALLOWED_HOSTS to the forwarded Host value.
• Only /mcp is served; POST bodies are capped at 1 MiB (413 above that), unsupported methods get 405, and unknown paths get 404.

Deploying over a VPN mesh (Tailscale example)

A common topology: your agent runs on a public server, and one or more device hosts (machines with USB-attached phones) are joined to a private mesh such as a Tailscale tailnet. Nothing needs to be exposed to the public internet — the agent reaches device hosts through the mesh.

Shape A — bind the mesh interface directly. On each device host, set the token, bind to the mesh IP (or 0.0.0.0), and allow the hostname the agent will dial:

ADBMCP_HTTP_TOKEN= ADBMCP_HTTP_ALLOWED_HOSTS='phonehost.tailnet-name.ts.net:3331,127.0.0.1:3331,localhost:3331' \
  adbmcp --http --host 0.0.0.0 --port 3331

WireGuard encrypts mesh traffic; the bearer token stays as the application-level gate so a misconfigured ACL or a compromised mesh member still cannot touch your devices. ALLOWED_HOSTS must contain the exact Host header the agent sends — MagicDNS name and port. Note the override replaces the derived loopback defaults, so loopback entries are re-added for local health checks.

Shape B — loopback + tailscale serve (nice for always-on hosts). Keep adbmcp bound to 127.0.0.1 (optionally with a token still set), then let Tailscale expose it:

adbmcp --http --host 127.0.0.1 --port 3331 &
tailscale serve --bg --https=443 http://127.0.0.1:3331   # --https=443 is the default mode

Keep the token set even in this shape — tailscale serve terminates TLS and limits reachability to the tailnet, but adbmcp should still authenticate its clients. Point the agent at https://phonehost.tailnet-name.ts.net/mcp (tailscale serve passes the original Host header through, so the portless ADBMCP_HTTP_ALLOWED_HOSTS entry is correct here).

Caveats that apply to both shapes: one adbmcp node per device host (the agent configures one MCP server entry per host — there is no cross-host device registry); sessions live until the client deletes them or the process restarts, so a device host that suspends or redeploys drops its logcat streams and agents must re-initialize; and provision the token to the agent out-of-band (secret manager, not chat).

Tools

device is optional on every device-scoped tool and required when more than one device is connected. Annotation columns: RO = readOnlyHint, D = destructiveHint, I = idempotentHint, O = openWorldHint.

Also shipped:

• Resource adb://devices — live device list as JSON (serial, state, model, allowed). State is never cached; re-read the resource to refresh.
• Prompts — debug_crash, install_and_launch, capture_bug_report: step-by-step orchestrations of the tools above.

uninstall_package, grant_permission, revoke_permission and clear_app_data are the tools with destructiveHint: true; shell, push_file, connect, disconnect and wireless_pair are the openWorldHint: true tools. They are never merged with read-only tools, so hosts can auto-approve reads and confirm writes.

Configuration

Safety notes

• Annotations are advisory, guardrails are authoritative. The host decides what to auto-approve; adbmcp enforces its own limits regardless: blocked shell patterns, the device allowlist, remote push roots, and the pull overwrite check.
• shell is arbitrary code execution on the device. It is annotated as not read-only and open-world, blocklisted by default, and documented as the escape hatch — keep shell disabled or prefix-restricted (ADBMCP_SHELL_ALLOWED_PREFIXES) on shared or CI machines. The default blocklist covers reboot/power-state changes, su, mkfs, wipe, rm of / (including split/reordered flags and the /* glob), and pipelines into sh/bash such as curl … | sh or … | sudo bash. This is a guardrail, not a sandbox: a deliberately obfuscated command can still get through. A pattern-based guardrail: matching runs on the raw command text, including inside quotes, so even prose like echo "use curl | sh to install" is refused — precision always yields to safety here. maintainer can replace the patterns with ADBMCP_SHELL_BLOCKED_PATTERNS.
• uninstall_package deletes app data unless keep_data: true. clear_app_data deletes app data permanently and is refused unless the package is listed in ADBMCP_CLEAR_ALLOWED_PACKAGES (unset/empty refuses every clear). grant_permission / revoke_permission change an app’s granted permissions. All four are marked destructiveHint: true.
• Device scoping is explicit. With multiple devices connected, calls without device fail with MULTIPLE_DEVICES and the candidate serials instead of guessing.
• Filesystem writes are bounded. pull_file never overwrites silently; push_file refuses writes outside the allowed remote roots and rejects .. traversal and relative paths. Root containment is lexical: it does not resolve on-device symlinks, so a link pre-created inside an allowed root (e.g. /data/local/tmp/x -> /data/system) can still redirect a push outside it.
• No privilege escalation. adbmcp never runs adb root/su itself and never retries a permission failure with elevation.
• The adb server is shared host state. adbmcp never kills or restarts it implicitly; adb_server_restart exists for the version-conflict case and says so in its description.
• Logcat streams are cleaned up. Streams are killed on stop_logcat_stream, and all remaining streams are terminated on SIGINT/SIGTERM (server shutdown).

Development

npm install
npm run build      # tsc -> dist/
npm test           # vitest, no adb binary or device required
npm run typecheck

Tests drive a fake adb runner and a fake stream spawner, so the whole suite runs without platform-tools, a device or an emulator. Layout:

src/
  index.ts            entrypoint: stdio by default, --http for Streamable HTTP
  http.ts             HTTP sessions, bearer auth, loopback guard, DNS-rebinding allowlist
  server.ts           assembles config + runner + tools/resources/prompts
  config.ts           env config, shell/device/push/clear guardrails
  devices.ts          device parsing, resolution rule, list_devices tool
  adb/runner.ts       subprocess per call: -s scoping, timeouts, head+tail caps
  adb/errors.ts       typed causes mapped from adb stderr/exit codes
  streams/registry.ts long-running logcat handles + ring buffer
  tools/              one module per tool group (34 tools, MVP + v2.0 items 1–6)
  resources/devices.ts, prompts/index.ts
test/                 vitest suites (fakes in test/helpers/)

Status

Implements the MVP plus v2.0 items 1–7 from the design (§4.2): reverse port forwards and structured forward/reverse listings, pm grant/revoke plus allowlist-gated clear_app_data, wireless TCP/IP connect/disconnect/wireless_pair, first-class input injection (tap, swipe, type_text, key_event — typed schemas that fix the input text quoting footgun, no DSL), the curated dumpsys_query, and the pulled-forward Streamable HTTP transport. v0.4.0 was a hardening/polish release (no new tools): shell guardrails now also block pipe-to-shell payloads and split/globbed root-deleting rm, address-targeted disconnect failures are reported as typed errors, and reverse_port rejects forward-only device-side specs pre-spawn. v0.5.0 adds Streamable HTTP (/mcp, stateful sessions, one shared device/stream context, optional bearer auth, loopback binding guard, DNS-rebinding protection). Not implemented: screenrecord, bugreport, iOS, emulator lifecycle management. Windows is best-effort (POSIX-first, like most of the ecosystem).