adb-mcp

---

Inicie um AVD, tire screenshots, leia a hierarquia da UI, toque/deslize/digite, defina um bloqueio de dispositivo, leia logcat, execute builds e testes Gradle. 78 ferramentas, do Claude Code, Cursor, VS Code ou qualquer cliente MCP via stdio.

É a contraparte Android do XcodeBuildMCP, construído sobre o Go MCP SDK oficial.

Android é uma marca comercial da Google LLC. adb-mcp é uma ferramenta independente e não oficial construída para Android e não é afiliada, patrocinada ou endossada pela Google. O robô Android acima é reproduzido/modificado a partir de trabalho criado e compartilhado pela Google e usado de acordo com os termos descritos na Licença de Atribuição Creative Commons 3.0.

Por quê

Controlar Android manualmente significa um longo manual de comandos adb brutos, e é fácil errar (coordenadas de toque desatualizadas, screenshots corrompidos por CRLF, esquecer exec-out, adivinhar coordenadas a partir de uma imagem reduzida). Este servidor incorpora esse conhecimento em suas ferramentas, para que o agente não precise reaprender:

• Screenshots usam exec-out screencap (sem corrupção por CRLF) e são automaticamente reduzidos para que o leitor de imagens os aceite.
• describe_ui retorna o centro de cada elemento em pixels reais do dispositivo (para que os toques acertem onde você quer, sem adivinhar pela imagem) e tenta novamente a falha transitória "could not get idle state" por conta própria.

O fluxo de trabalho em si é entregue como recursos legíveis que o agente pode consultar no meio da tarefa (o loop observar→agir, tratamento de PIN/bloqueio nativo, triagem de crash, veja abaixo) em vez de reaprendê-los a cada sessão.

Começando

1. Pré-requisitos

• Android SDK com platform-tools (adb) e emulator. O servidor o encontra via $ANDROID_HOME / $ANDROID_SDK_ROOT, caso contrário, o padrão da plataforma (~/Library/Android/sdk no macOS). Se o seu cliente MCP iniciar o servidor sem essas variáveis definidas, passe --sdk /path/to/sdk na configuração do cliente em args (o servidor então a exporta, para que o Gradle também encontre o SDK). doctor imprime o local que ele resolveu.
• Pelo menos um AVD (crie um no Device Manager do Android Studio).

Go não é necessário: os lançamentos incluem binários pré-compilados, e ele só é necessário para compilar a partir do código-fonte.

2. Instalação

No macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/iksnerd/adb-mcp/main/install.sh | sh

O script (install.sh) escolhe o arquivo correto para o seu SO/arquitetura, verifica seu SHA-256 contra o checksums.txt do lançamento, e instala em ~/.local/bin (substitua com BIN_DIR=...; fixe uma versão com VERSION=v0.17.0).

Prefere baixar o binário você mesmo? Os arquivos de cada plataforma (macOS, Linux e Windows, amd64 e arm64) estão na página de Releases, cada um com um checksum em checksums.txt. No Windows, baixe o zip windows_amd64 ou windows_arm64 e coloque adb-mcp.exe em algum lugar do seu PATH.

Depois de instalado, mantenha-se atualizado com o atualizador integrado. Ele busca o lançamento mais recente, verifica seu checksum e substitui o binário no lugar:

adb-mcp update

O registro abaixo inicia o servidor pelo nome simples adb-mcp, então ele deve estar no seu $PATH (which adb-mcp deve resolver; o instalador avisa se ~/.local/bin não estiver nele). Caso contrário, aponte o cliente para o caminho absoluto do binário.

3. Registre no seu cliente MCP

Claude Code:

claude mcp add adb -- adb-mcp

(Ao trabalhar dentro deste próprio repositório, o .mcp.json incluído é detectado automaticamente, sem necessidade de registro.)

Cursor / VS Code: instalação em um clique (assume que adb-mcp está no seu PATH do passo 2):

Qualquer outro cliente (Windsurf, Codex, …): execute adb-mcp via stdio. O formato de configuração usual:

{
  "mcpServers": {
    "adb": { "command": "adb-mcp" }
  }
}

Para confirmar que está conectado, peça ao seu agente para "iniciar um emulador e tirar um screenshot".

A partir do código-fonte (Go 1.26+)

make install                 # builds ./bin/adb-mcp and copies it to ~/.local/bin
# or:
go build -o bin/adb-mcp ./cmd/adb-mcp
# or straight from the module (note the /cmd/adb-mcp suffix):
go install github.com/iksnerd/adb-mcp/cmd/adb-mcp@latest

Ferramentas

78 ferramentas em dez áreas. Toda ferramenta voltada ao dispositivo aceita um serial opcional (adb -s). Omita-o com um dispositivo conectado, ou passe um de list_devices com vários. Referência completa: docs/TOOLS.md.

• Emulador / dispositivo: iniciar, listar, aguardar inicialização, desligar, conectar via Wi-Fi, adb_reverse encaminhamento de porta (Metro!)
• Observar: screenshot para ver (funciona em dobráveis com múltiplas telas, escolha um painel com display), describe_ui para centros de elementos em pixels reais, com a janela superior focada (detecte um prompt biométrico, ou o app errado, obstruindo seu alvo via package opcional), modos filter/query/compact, e uma contagem de nós ocultos para que a ausência seja confiável
• Interagir: tocar, tap_on_text/tap_element (endereçados por id), deslizar, arrastar, toque longo, digitar, combinações de teclas, teclados PIN, wait, run_sequence (etapas em lote + guardas em uma única chamada, o que evita que fluxos com temporizadores nativos sejam perturbados por idas e voltas por etapa); verify_change opcional informa se um toque/tecla realmente mudou a UI; via_accessibility opcional em tap_on_text/tap_element (EXPERIMENTAL) despacha um clique de acessibilidade real para visualizações nativas que um toque por coordenada não alcança, veja bridge/README.md
• Bloqueio / Keystore / Biometria: definir/remover uma tela de bloqueio segura, verificar o estado do bloqueio, has_biometric_enrolled + fingerprint_touch/finger_remove para satisfazer um BiometricPrompt no emulador
• Controles estendidos (emulador): send_sms (OTP/2FA), phone_call, set_battery (também funciona em dispositivos reais via dumpsys), cellular (roaming/sinal fraco/aceleração), set_sensor (acelerômetro/luz/…), rotate_screen, avd_snapshot, controlando o painel somente console do emulador que describe_ui não consegue ver
• Ciclo de vida do app: instalar/desinstalar, iniciar/parar, app_state (pid(s) em execução + bundle Metro-vs-embutido), launch_dev_client (build de desenvolvimento Expo → Metro, pulando o Dev Launcher), reload_app/open_dev_menu, limpar dados, permissões, deep links, enviar/receber arquivos, last_crash
• Logs e captura: logcat único ou em streaming (filtros de substring/prioridade/tag, janela de tempo since, redact opcional para mascarar tokens/senhas/chaves de API antes da saída), clear_logcat, last_crash, gravação de tela
• Ambiente e diagnóstico: modo escuro, localização simulada, barra de status limpa, stay_awake (impeça que uma tela que escurece facilmente estrague seus screenshots), doctor
• Build e teste Gradle: assembleDebug, testes unitários, testes instrumentados, cobertura de testes unitários JVM via JaCoCo (get_coverage_report/get_file_coverage), descoberta de tarefas + variantes + módulos (list_gradle_variants/list_gradle_projects), build_and_run único
• Padrões de sessão: fixe project_dir/serial uma vez (session_set_defaults) para que um projeto multi-módulo/multi-variante ou uma sessão multi-dispositivo não precise repeti-los em cada chamada

O conhecimento de controle em si é entregue como cinco recursos MCP (android://guide/*) que o cliente pode listar e ler. Veja docs/TOOLS.md para os URIs, ou vá direto para android://guide/driving para o loop principal abaixo.

O loop principal

observar → localizar → agir → re-observar. screenshot para ver, describe_ui para obter centros em pixels reais, tap/tap_on_text/swipe/input_text para agir, depois screenshot novamente para confirmar. Leia android://guide/driving para o loop completo e as armadilhas que desperdiçam turnos.

Desenvolvimento

make check     # go vet + go test (unit tests need no emulator)
make run       # run over stdio for manual JSON-RPC poking

Estrutura:

cmd/adb-mcp/main.go        entry: subcommands (update/version) or serve MCP over stdio
internal/tools/            thin MCP tool bindings
internal/adb/              the device layer: an adb.Client whose methods are the commands
internal/gradle/           host-side Gradle: build, find APKs, parse test reports
internal/uiauto/           pure uiautomator-hierarchy model + parsing (unit-tested)
internal/sdk/              resolves the Android SDK (adb/emulator paths, PATH env)
internal/concurrent/       RunAll/RunIndexed: fan out independent I/O calls, join, done
internal/guides/           the skill guides, embedded and served as MCP resources
internal/selfupdate/       the `adb-mcp update` release fetch/verify/swap
internal/bridgeupdate/     the `adb-mcp bridge install` release fetch/verify/install

As dependências apontam apenas para dentro (tools → adb, gradle, uiauto → sdk), e cada adaptador internal/tools/<domain>.go espelha um arquivo de execução com o mesmo nome (comandos de dispositivo são métodos adb.Client). Mapa completo, o grafo de pacotes e as regras para adicionar uma ferramenta: ARCHITECTURE.md.

Documentação

• adb-mcp.com: página inicial
• docs/TOOLS.md: referência completa ferramenta por ferramenta e os guias de recursos
• ARCHITECTURE.md: a convenção de espelhamento, a estrutura de pacotes e como adicionar uma ferramenta
• docs/CHANGELOG.md: trabalho entregue, do mais recente ao mais antigo
• docs/BACKLOG.md: ideias em aberto e lacunas de paridade com o XcodeBuildMCP

Contribuindo

Veja CONTRIBUTING.md para configuração e convenções. Encontrou um problema de segurança? Veja SECURITY.md em vez de abrir uma issue pública. Licenciado sob MIT.