adb-automation-mcp

An MCP server exposing Android Debug Bridge (ADB) capabilities as typed, documented tools and resources.

Full documentation — architecture, decision log, per-tool reference, and client integration guides.

Install

uvx adb-automation-mcp
# or
pip install adb-automation-mcp

Quickstart

uv sync
uv run adb-automation-mcp

Talks to the adb binary on PATH by default. For real-device setup, the fake backend, the full tool list, and per-client integration guides (Claude Code, Claude Desktop, ...), see the docs site.

Installation prompt

Prefer not to configure this by hand? Hand the AI-assisted install prompt to an AI coding assistant that can run shell commands and edit MCP config (Claude Code, GitHub Copilot in agent mode, ...) — it detects/installs uv, resolves adb's absolute path, and registers this server for you.

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). Every real-device env var is shown below — all are optional, see the full reference for defaults and details (including ADB_AUTOMATION_BACKEND, a testing-only switch to the fake in-memory backend, not something a real client config needs):

{
  "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"
      }
    }
  }
}

• ADB_AUTOMATION_ADB_PATH — explicit path to the adb binary; MCP clients usually launch the server with a minimal environment that doesn't include your shell's PATH customizations, so set this explicitly rather than relying on PATH resolution
• ADB_AUTOMATION_TIMEOUT_S — per-command timeout in seconds
• ADB_AUTOMATION_ALLOW_DESTRUCTIVE=1 — allow destructive-category tools (e.g. remove_user); denied by default
• ADB_AUTOMATION_LOCAL_ROOT — the folder on this machine where file-saving tools (pull_file, stop_log_session, take_screenshot) are allowed to write; unset means those tools refuse to write anywhere

Testing

uv run pytest        # meta (Layer 0), unit (Layer 1), and e2e (Layer 3) tests
uv run mypy src       # strict type checking
uv run ruff check .   # lint
uv run mkdocs build --strict   # docs site

Tools

111 tools. Full signatures, docstrings, and worked examples are in the tool reference. Tools marked † are destructive — not registered unless ADB_AUTOMATION_ALLOW_DESTRUCTIVE=1.

License

MIT