ADB Automation MCP

adb-automation-mcp

Um servidor MCP que expõe capacidades do Android Debug Bridge (ADB) como ferramentas e recursos tipados e documentados. Veja Arquitetura para entender como o sistema é estruturado.

Requisitos

• Python ≥ 3.10
• uv
• Android platform-tools (adb) — necessário apenas para o backend real; o backend fake (abaixo) não precisa de nada relacionado a dispositivos instalado.

Como executar

uv sync
uv run adb-automation-mcp

Por padrão, isso se comunica com o binário adb encontrado em PATH. Configure-o com variáveis de ambiente:

Variável de ambiente	Finalidade	Padrão
ADB_AUTOMATION_BACKEND=fake	Usa o backend fake determinístico em vez do adb real — sem necessidade de binário adb ou dispositivo	não definido (backend real)
ADB_AUTOMATION_ADB_PATH	Caminho explícito para o binário adb	não definido (resolvido via PATH)
ADB_AUTOMATION_TIMEOUT_S	Tempo limite por comando, em segundos	10
ADB_AUTOMATION_ALLOW_DESTRUCTIVE=1	Optar por ferramentas da categoria destructive (ex.: uninstall_package, remove_user, restart_adbd_as_root)	não definido (negado por padrão)
ADB_AUTOMATION_LOCAL_ROOT	A pasta nesta máquina onde as ferramentas de salvamento de arquivos podem gravar	não definido — essas ferramentas se recusam a gravar em qualquer lugar até que seja definido

ADB_AUTOMATION_ADB_PATH importa mais do que parece: um cliente MCP (Claude Code, Claude Desktop,...) inicia este servidor com um ambiente mínimo que geralmente não inclui as personalizações de PATH do seu shell, então o adb resolvendo corretamente no seu terminal não significa que ele será resolvido dentro do servidor iniciado. Defina o caminho explicitamente ao integrar com um cliente (veja Integrações).

# 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

Onde os arquivos salvos vão (ADB_AUTOMATION_LOCAL_ROOT)

Algumas ferramentas salvam um arquivo nesta máquina: pull_file (copia um arquivo do dispositivo), stop_log_session (salva um log capturado) e take_screenshot (salva o PNG e retorna seu caminho — não retorna os bytes da imagem inline). ADB_AUTOMATION_LOCAL_ROOT é a única pasta onde essas ferramentas podem gravar — não há local de fallback, então elas se recusam a executar até que seja definido.

pull_file e stop_log_session aceitam um argumento local_path, um caminho dentro dessa pasta. Com ADB_AUTOMATION_LOCAL_ROOT=/home/you/adb-downloads definido:

• pull_file(..., local_path="ui-dump.xml") grava em /home/you/adb-downloads/ui-dump.xml
• stop_log_session(..., local_path="session1.log") grava em /home/you/adb-downloads/session1.log
• take_screenshot(...) grava em /home/you/adb-downloads/screenshots/screenshot-<serial>-<timestamp>.png (ou screenshots/<filename>.png quando filename= é fornecido) e retorna esse caminho absoluto

Um local_path que tenta escapar dessa pasta — ../elsewhere, ou um caminho absoluto apontando para outro lugar — é rejeitado em vez de ser gravado em qualquer lugar.

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

Configuração do cliente MCP

Adicione isso ao mcp.json do seu cliente (ex.: config do Claude Desktop, ou o .mcp.json de um projeto Claude Code — veja Integrações). Outros clientes usam uma estrutura semelhante de command / args / env, mas com uma chave de nível superior diferente (o .vscode/mcp.json do VS Code Copilot, por exemplo, usa servers em vez de mcpServers) — consulte a documentação MCP do seu próprio cliente para o wrapper exato. Cada variável de ambiente da tabela acima é opcional; mostrada aqui com valores de exemplo:

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

Ferramentas disponíveis

111 ferramentas. Veja a Referência de Ferramentas para a assinatura completa, docstring e exemplo prático de cada ferramenta — gerada diretamente do código-fonte, então não pode ficar dessincronizada com o que o servidor realmente expõe. O README tem a lista completa por módulo.

Testes

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

Licença

MIT