adbfleet-mcp

adbfleet-mcp

Um servidor MCP que permite a um assistente de IA trabalhar com muitos dispositivos Android via ADB ao mesmo tempo. Ele pode listar dispositivos, conectar endpoints de rede, verificar a saúde dos dispositivos, instalar APKs e, se você permitir, executar comandos shell. Cada ação é executada em paralelo nos dispositivos que você selecionar e retorna resultados por dispositivo.

Funciona com qualquer dispositivo que o adb possa alcançar: celulares USB, emuladores, depuração Wi-Fi, caixas ADB-over-TCP e celulares em nuvem, como o FoxPhone.

Mantido pela FoxPhone, celulares Android em nuvem. É construído sobre a biblioteca adbfleet.

Ferramentas

Ferramenta	O que faz	Habilitada por padrão
list_devices	Lista dispositivos conectados com serial, estado, tipo (usb/emulador/rede), modelo, @index e o nome e as tags do seu inventário.	sim (somente leitura)
device_health	Modelo, versão do Android, bateria, temperatura, espaço livre em /data, tempo de atividade e tamanho da tela de cada dispositivo.	sim (somente leitura)
connect_devices	Executa adb connect em endpoints host[:port] em paralelo, com tentativas. A porta padrão é 5555.	sim
disconnect_devices	Executa adb disconnect em endpoints.	sim
install_apk_on_devices	Instala um APK, ou um conjunto de APKs divididos, a partir da máquina que executa o servidor. Suporta -r, -g e -d. Um dispositivo é considerado como falha quando o adb imprime Failure [...], mesmo que o adb saia com código 0.	sim (--no-install desativa)
run_shell_on_devices	Executa um comando adb shell não interativo em cada dispositivo selecionado.	não: inicie o servidor com --allow-shell

Padrões de segurança

• Shell desativado, a menos que você o ative. run_shell_on_devices não é registrado até que você inicie o servidor com --allow-shell ou defina ADBFLEET_MCP_ALLOW_SHELL=1.
• A seleção de dispositivos deve ser explícita. Ferramentas que agem em dispositivos precisam de serials (seriais, nomes de inventário, prefixos de serial ou @N) ou all_devices: true. Se nenhum for fornecido, nada é executado.
• Tempos limite em tudo. Cada dispositivo tem um tempo limite (30 s por padrão, --timeout), e os tempos limite solicitados são limitados por --max-timeout, 600 s por padrão. Quando um comando expira, seu processo adb é encerrado.
• Limites. --max-devices (padrão 50) rejeita chamadas que visam muitos dispositivos. A saída de cada dispositivo é truncada em --max-output caracteres.
• Verificações de APK. Os arquivos devem existir e terminar em .apk. --apk-dir DIR limita as instalações a arquivos dentro de uma pasta.
• Sem credenciais e sem APIs de fornecedores. O servidor apenas chama o binário padrão adb.

Requisitos

• Node.js 18 ou mais recente
• Android platform-tools (adb). O servidor o procura em $ADBFLEET_ADB, depois em $ANDROID_HOME/platform-tools e, em seguida, no seu PATH.

Configuração

Claude Desktop, Cursor ou qualquer cliente MCP que use o formato mcpServers:

{
  "mcpServers": {
    "adbfleet": {
      "command": "npx",
      "args": ["-y", "adbfleet-mcp"]
    }
  }
}

Para ativar comandos shell e limitar instalações de APK a uma pasta:

{
  "mcpServers": {
    "adbfleet": {
      "command": "npx",
      "args": ["-y", "adbfleet-mcp", "--allow-shell", "--apk-dir", "/home/me/builds"],
      "env": { "ADBFLEET_ADB": "/opt/android-sdk/platform-tools/adb" }
    }
  }
}

Opções

--allow-shell        expose run_shell_on_devices (off by default; or ADBFLEET_MCP_ALLOW_SHELL=1)
--no-install         do not expose install_apk_on_devices
--apk-dir DIR        only allow installing APKs from inside DIR
--timeout SEC        default per-device timeout (30)
--max-timeout SEC    upper limit for any requested timeout (600)
--jobs N             devices handled in parallel (8)
--max-devices N      refuse calls that target more devices than this (50)
--max-output N       truncate per-device stdout/stderr to N chars (16000)
--inventory FILE     adbfleet fleet.json with device names and tags

O servidor lê o mesmo inventário fleet.json que a CLI adbfleet, de --inventory, $ADBFLEET_INVENTORY, ./fleet.json ou ~/.config/adbfleet/fleet.json. Isso permite que o assistente se refira aos dispositivos pelo nome, por exemplo, "serials": ["cloud-01"].

Usando com celulares em nuvem FoxPhone

Os celulares em nuvem FoxPhone são dispositivos Android que rodam na nuvem. Quando o acesso ADB está habilitado, cada um tem um endpoint host:port e, a partir daí, funciona como qualquer outro dispositivo de rede. Aqui está uma conversa típica com seu assistente:

1. "Conecte meus celulares em nuvem 203.0.113.10:5555 e 203.0.113.11:5555." O assistente chama connect_devices.
2. "Quais dispositivos estão online e algum tem menos de 1 GB livre?" O assistente chama list_devices e depois device_health.
3. "Instale /home/me/builds/app-release.apk em todos eles." O assistente chama install_apk_on_devices com all_devices: true.
4. Com --allow-shell ativado: "Abra com.example.app nos celulares em nuvem." O assistente chama run_shell_on_devices com monkey -p com.example.app -c android.intent.category.LAUNCHER 1.

Os endereços acima são exemplos de documentação, então substitua-os pelos endpoints exibidos para seus dispositivos. Os mesmos passos funcionam com qualquer dispositivo ou provedor ADB-over-TCP.

Desenvolvimento

npm install
npm test        # node:test with an in-memory MCP client and a mocked adb (no devices needed)

Licença

MIT © Foxphone LLC. Consulte LICENSE.