agent-droid-bridge

A Ponte Agent Droid concede a agentes de IA controle programático sobre dispositivos Android e emuladores via ADB, exposto como um servidor MCP.

GitHub

Experimente este MCPPatrocinado

Documentação

Agent Droid Bridge

Agent Droid Bridge é um servidor MCP que conecta agentes de IA a dispositivos Android e emuladores via ADB. Ele é construído para automação mobile, testes de aplicativos, análise dinâmica e engenharia reversa: expondo toda a superfície do ADB como ferramentas estruturadas que qualquer cliente de IA compatível com MCP pode chamar diretamente. Se o ADB pode fazer, um agente pode fazer.

Ferramentas projetadas para propósito específico retornam respostas estruturadas e mínimas. Sem despejos de XML bruto, sem contexto desperdiçado — agentes permanecem rápidos em sessões longas.

Demonstração

A demonstração acima executa algumas tarefas simples para mostrar o que um agente conectado pode fazer, e isso é apenas a ponta do iceberg:

Instala o aplicativo Paint, abre-o e desenha uma casa calculando coordenadas de pixels para as paredes e o telhado
Abre o navegador do dispositivo, pesquisa por "MCP Wikipedia", navega até a página de resultados e tira uma captura de tela
Abre a Calculadora, calcula 1337 × 42 e extrai o resultado para a máquina host
Abre Contatos, cria uma nova entrada com nome e número de telefone e confirma que foi salva
Abre o Calendário e agenda um compromisso para uma data específica
Abre Configurações e alterna o modo escuro
Extrai o APK da Calculadora do dispositivo para a máquina host
Instala o Notepad, escreve um resumo de uma frase de cada tarefa concluída e tira uma captura de tela final

O que ele faz

Ferramentas

14 ferramentas integradas para captura de tela, inspeção de UI, leitura de texto, extração de elementos, entrada por toque e deslize, entrada de texto, eventos de keycode, inicialização de aplicativos, comandos ADB e inspeção de dispositivos
O pacote app_manager adiciona 9 ferramentas para gerenciamento de pacotes, ciclo de vida de aplicativos, extração de APK, permissões e injeção de intents. Carregue-o com ADB_EXTRA_TOOL_PACKS=app_manager
A disponibilidade das ferramentas é refletida nas instruções de inicialização do servidor. Os agentes recebem um catálogo preciso no momento da conexão

Manipulação de dispositivos

Detecta automaticamente um único dispositivo conectado; solicita seleção quando vários dispositivos estão presentes
Executa via stdio, compatível com qualquer cliente de IA com suporte a MCP
Respostas estruturadas em vez de despejos de XML bruto, mantendo o contexto do agente enxuto em execuções de automação longas

Segurança

Dois modos de execução: unrestricted (acesso ADB completo, com denylist opcional) e restricted (somente allowlist, bloqueia tudo que não for explicitamente permitido)
Defina ADB_ALLOW_SHELL=false para desabilitar todos os comandos shell, independentemente do modo
Oculte ferramentas específicas do agente com ADB_DENIED_TOOLS
Todos os comandos são analisados via shlex. Nenhuma injeção de shell é possível

Observabilidade

Gravador de sessão opcional registra cada chamada de ferramenta, comando ADB e evento de segurança em arquivos JSONL estruturados. Ative com MCP_LOG_ENABLED=true e MCP_LOG_DIR

Casos de uso

QA mobile e automação de testes Automatize fluxos de UI em dispositivos reais e emuladores sem modificar o aplicativo ou escrever código de teste. Toque, deslize, digite, leia o conteúdo da tela, tire capturas de tela — tudo a partir de um prompt em linguagem natural.

Pesquisa de segurança de aplicativos Extraia APKs, inspecione permissões declaradas, dispare intents arbitrários e observe o comportamento em tempo de execução na tela. Sem instrumentação, sem necessidade de jailbreak.

Análise dinâmica Inicie aplicativos em estados controlados, conduza interações de UI, capture o estado da tela em cada etapa e extraia artefatos — tudo roteirizável por meio de um agente de IA.

Desenvolvimento e depuração Instale builds, verifique estados de UI, consulte informações de aplicativos e execute comandos ADB sem sair do seu ambiente de codificação.

Instalação

uvx agent-droid-bridge

Sem necessidade de clonagem ou ambientes virtuais. Requer Python 3.11+ e ADB instalado no seu host.

uvx é fornecido pelo uv. Se você não o tiver: curl -LsSf https://astral.sh/uv/install.sh | sh

Para instalar a partir do código-fonte, consulte docs/setup.md — Opção B.

Para verificar a instalação: uvx agent-droid-bridge --help

Início rápido

Instale o ADB — consulte docs/setup.md para instruções específicas por plataforma
Conecte um dispositivo Android ou inicie um emulador
Adicione o servidor à configuração do seu cliente MCP:

{
  "mcpServers": {
    "agent-droid-bridge": {
      "command": "uvx",
      "args": ["agent-droid-bridge"],
      "env": {
        "ADB_EXECUTION_MODE": "unrestricted",
        "ADB_ALLOW_SHELL": "true",
        "ADB_PATH": "adb",
        "ADB_EXTRA_TOOL_PACKS": "",
        "MCP_LOG_ENABLED": "false",
        "MCP_LOG_DIR": "~/logs/agent-droid-bridge"
      }
    }
  }
}

Para habilitar o registro de sessão, defina MCP_LOG_ENABLED como "true" e atualize MCP_LOG_DIR para um caminho gravável na sua máquina.

Variável	Padrão	Descrição
`ADB_EXECUTION_MODE`	`unrestricted`	Modo de segurança. `unrestricted` permite todos os comandos shell (com denylist opcional); `restricted` permite apenas comandos em `ADB_SHELL_ALLOWLIST`.
`ADB_ALLOW_SHELL`	`true`	Defina como `false` para bloquear todos os comandos `adb shell`, independentemente do modo de execução.
`ADB_PATH`	`adb`	Caminho para o binário ADB. Substitua por um caminho completo se `adb` não estiver no PATH do seu sistema (por exemplo, `C:\platform-tools\adb.exe` no Windows).
`ADB_EXTRA_TOOL_PACKS`	(vazio)	Lista separada por vírgulas de pacotes de ferramentas extras para carregar. Defina como `app_manager` para habilitar 9 ferramentas adicionais de gerenciamento de aplicativos.
`MCP_LOG_ENABLED`	`false`	Defina como `true` para habilitar o registro de sessão. Requer `MCP_LOG_DIR`.
`MCP_LOG_DIR`	(nenhum)	Diretório onde os logs de sessão são gravados. Obrigatório quando `MCP_LOG_ENABLED` é `true`.

Solicite ao seu agente que use as ferramentas MCP agent-droid-bridge

Guia completo de configuração e referência de variáveis de ambiente: docs/setup.md

Ferramentas

Ferramenta	O que faz
`get_ui_hierarchy`	Retorna a tela atual como uma hierarquia de UI em XML
`take_screenshot`	Captura a tela como um PNG codificado em base64
`tap_screen`	Envia um gesto de toque em coordenadas de pixel
`swipe_screen`	Envia um gesto de deslize entre dois pontos durante uma determinada duração
`type_text`	Digita texto no campo de entrada focado
`press_key`	Envia um evento de keycode Android (Voltar, Início, Enter, etc.)
`launch_app`	Inicia um aplicativo pelo nome do componente `package/activity`
`execute_adb_command`	Executa um comando ADB ou ADB shell arbitrário
`list_devices`	Lista todos os dispositivos Android atualmente visíveis ao ADB com serial, estado e modelo
`snapshot_ui`	Tira um snapshot leve da UI e retorna um token para uso com `detect_ui_change`
`detect_ui_change`	Verifica se houve mudança na UI após uma ação; aceita um token de snapshot como linha de base; retorna a hierarquia somente quando solicitado
`get_screen_elements`	Analisa a hierarquia da UI e retorna elementos estruturados com coordenadas e propriedades de interação; suporta modos `tappable`, `interactive`, `input` e `all`
`get_screen_text`	Retorna todo o texto visível na tela ordenado de cima para baixo, como texto simples
`check_device_capabilities`	Retorna informações estruturadas do dispositivo — identidade, postura de segurança e especificações de hardware — em uma única chamada; suporta modos `identity`, `security`, `hardware` e `all`

Pacotes de ferramentas extras

Pacotes opcionais estendem o conjunto principal de ferramentas. Habilite-os definindo ADB_EXTRA_TOOL_PACKS na configuração do seu cliente MCP. Consulte docs/extra-tool-packs.md.

app_manager

Gerenciamento de pacotes, controle do ciclo de vida de aplicativos, extração de APK, gerenciamento de permissões e injeção de intents.

Ferramenta	O que faz
`list_packages`	Lista pacotes instalados com filtragem, pesquisa e níveis de detalhe opcionais
`get_app_info`	Retorna metadados estáticos completos de um único aplicativo instalado
`install_app`	Instala um APK de um caminho do host no dispositivo
`uninstall_app`	Remove um aplicativo instalado pelo nome do pacote
`pull_apk`	Extrai o APK instalado do dispositivo para o host
`manage_permission`	Concede, revoga, verifica ou lista permissões de tempo de execução de um aplicativo
`launch_app_extra`	Inicia um aplicativo pelo nome do pacote, resolvendo automaticamente a atividade do launcher
`manage_app`	Controla o estado de tempo de execução do aplicativo — parar, limpar dados, limpar cache, habilitar, desabilitar
`inject_intent`	Dispara um intent em um componente via `am start`, `am broadcast` ou `am startservice`

Referência completa de parâmetros: docs/tools.md

Configuração

Configure o servidor inteiramente pelo bloco env do seu cliente MCP. Nenhum arquivo para editar. O bloco de ambiente no Início Rápido acima cobre as configurações mais comuns. Para a referência completa, incluindo filtragem de segurança, visibilidade de ferramentas e timeouts, consulte docs/configuration.md.

Para usar um arquivo de configuração YAML, defina ADB_CONFIG_SOURCE=yaml. Consulte docs/configuration.md para detalhes.

A gravação de sessão é separada. Habilite-a com MCP_LOG_ENABLED=true e MCP_LOG_DIR. Referência completa: docs/logging.md.

Documentação

Arquivo	Descrição
docs/setup.md	Pré-requisitos, instalação e configuração do cliente MCP
docs/tools.md	Referência completa de parâmetros para todas as ferramentas
docs/configuration.md	Referência para variáveis de ambiente e `adb_config.yaml`
docs/logging.md	Gravador de sessão — arquivos de log, níveis, retenção e ativação
docs/extra-tool-packs.md	Pacotes de ferramentas extras — habilitando pacotes, o contrato do pacote e como escrever o seu próprio
docs/troubleshooting.md	Problemas comuns de configuração e problemas com ADB
docs/workflows.md	Fluxos de trabalho comuns com várias ferramentas e exemplos
CHANGELOG.md	Histórico de versões e mudanças

Contribuindo

Contribuições são bem-vindas. Consulte CONTRIBUTING.md para diretrizes sobre configuração, padrões de código e envio de pull requests. Para relatar uma vulnerabilidade de segurança, siga o processo em SECURITY.md — não abra uma issue pública.