ADB Automation MCP

adb-automation-mcp

An MCP server exposing Android Debug Bridge (ADB) capabilities as typed, documented tools and resources. See Architecture for how the system is put together.

Requirements

• Python ≥ 3.10
• uv
• Android platform-tools (adb) — only needed for the real backend; the fake backend (below) needs nothing device-related installed.

Running it

uv sync
uv run adb-automation-mcp

By default this talks to the adb binary found on PATH. Configure it with env vars:

Env var	Purpose	Default
ADB_AUTOMATION_BACKEND=fake	Use the deterministic fake backend instead of real adb — no adb binary or device needed	unset (real backend)
ADB_AUTOMATION_ADB_PATH	Explicit path to the adb binary	unset (resolved via PATH)
ADB_AUTOMATION_TIMEOUT_S	Per-command timeout, in seconds	10
ADB_AUTOMATION_ALLOW_DESTRUCTIVE=1	Opt in to destructive -category tools (e.g. uninstall_package, remove_user, restart_adbd_as_root)	unset (denied by default)
ADB_AUTOMATION_LOCAL_ROOT	The folder on this machine where file-saving tools are allowed to write	unset — those tools refuse to write anywhere until set

ADB_AUTOMATION_ADB_PATH matters more than it might seem: an MCP client (Claude Code, Claude Desktop,...) launches this server with a minimal environment that usually does not include your shell's PATH customizations, so adb resolving fine in your terminal doesn't mean it'll resolve inside the launched server. Set the path explicitly when integrating with a client (see Integrations).

# real device/emulator, explicit adb path
ADB_AUTOMATION_ADB_PATH=/path/to/platform-tools/adb uv run adb-automation-mcp

# deterministic fake backend, no adb required
ADB_AUTOMATION_BACKEND=fake uv run adb-automation-mcp

Where saved files go (ADB_AUTOMATION_LOCAL_ROOT)

A few tools save a file to this machine: pull_file (copies a file off the device), stop_log_session (saves a captured log), and take_screenshot (saves the PNG and returns its path — it does not return image bytes inline). ADB_AUTOMATION_LOCAL_ROOT is the one folder these tools are allowed to write into — there's no fallback location, so they refuse to run until it's set.

pull_file and stop_log_session take a local_path argument, a path inside that folder. With ADB_AUTOMATION_LOCAL_ROOT=/home/you/adb-downloads set:

• pull_file(..., local_path="ui-dump.xml") writes to /home/you/adb-downloads/ui-dump.xml
• stop_log_session(..., local_path="session1.log") writes to /home/you/adb-downloads/session1.log
• take_screenshot(...) writes to /home/you/adb-downloads/screenshots/screenshot-<serial>-<timestamp>.png (or screenshots/<filename>.png when filename= is given) and returns that absolute path

A local_path that tries to escape that folder — ../elsewhere, or an absolute path pointing somewhere else — is rejected rather than written anywhere.

ADB_AUTOMATION_LOCAL_ROOT=/home/you/adb-downloads uv run adb-automation-mcp

MCP client configuration

Add this to your client's mcp.json (e.g. Claude Desktop's config, or a Claude Code project's .mcp.json — see Integrations). Other clients use a similar command / args / env shape but a different top-level key (VS Code Copilot's .vscode/mcp.json, for instance, uses servers instead of mcpServers) — check your client's own MCP docs for the exact wrapper. Every env var from the table above is optional; shown here with example values:

{
  "mcpServers": {
    "adb-automation-mcp": {
      "command": "uvx",
      "args": ["adb-automation-mcp"],
      "env": {
        "ADB_AUTOMATION_ADB_PATH": "/path/to/platform-tools/adb",
        "ADB_AUTOMATION_TIMEOUT_S": "10",
        "ADB_AUTOMATION_ALLOW_DESTRUCTIVE": "1",
        "ADB_AUTOMATION_LOCAL_ROOT": "/path/to/local/root"
      }
    }
  }
}

Available tools

111 tools. See the Tool Reference for every tool's full signature, docstring, and worked example — generated directly from source, so it can't drift out of sync with what the server actually exposes. The README has the full per-module list.

Testing

uv run pytest        # registry contract, unit, and e2e tests
uv run mypy src       # strict type checking
uv run ruff check .   # lint

License

MIT