adbfleet-mcp

adbfleet-mcp

Un servidor MCP que permite a un asistente de IA trabajar con muchos dispositivos Android a través de ADB al mismo tiempo. Puede listar dispositivos, conectar endpoints de red, comprobar el estado de los dispositivos, instalar APKs y, si lo permites, ejecutar comandos de shell. Cada acción se ejecuta en paralelo en los dispositivos que elijas y devuelve resultados por dispositivo.

Funciona con cualquier dispositivo al que adb pueda llegar: teléfonos por USB, emuladores, depuración por Wi-Fi, dispositivos ADB sobre TCP y teléfonos en la nube como FoxPhone.

Mantenido por FoxPhone, teléfonos Android en la nube. Está construido sobre la biblioteca adbfleet.

Herramientas

Herramienta	Qué hace	Habilitada por defecto
list_devices	Lista los dispositivos conectados con su serial, estado, tipo (usb/emulador/red), modelo, @index, y el nombre y las etiquetas de tu inventario.	sí (solo lectura)
device_health	Modelo, versión de Android, batería, temperatura, espacio libre en /data, tiempo de actividad y tamaño de pantalla de cada dispositivo.	sí (solo lectura)
connect_devices	Ejecuta adb connect en endpoints host[:port] en paralelo, con reintentos. El puerto predeterminado es 5555.	sí
disconnect_devices	Ejecuta adb disconnect en endpoints.	sí
install_apk_on_devices	Instala un APK, o un conjunto de APKs divididos, desde la máquina que ejecuta el servidor. Admite -r, -g y -d. Un dispositivo se considera fallido cuando adb imprime Failure [...], aunque adb termine con código 0.	sí (--no-install lo desactiva)
run_shell_on_devices	Ejecuta un comando adb shell no interactivo en cada dispositivo seleccionado.	no: inicia el servidor con --allow-shell

Valores predeterminados de seguridad

• El shell está desactivado a menos que lo actives. run_shell_on_devices no se registra hasta que inicies el servidor con --allow-shell o establezcas ADBFLEET_MCP_ALLOW_SHELL=1.
• La selección de dispositivos debe ser explícita. Las herramientas que actúan sobre dispositivos necesitan serials (serials, nombres de inventario, prefijos de serial o @N) o all_devices: true. Si no se proporciona ninguno, no se ejecuta nada.
• Tiempos de espera en todo. Cada dispositivo tiene un tiempo de espera (30 s por defecto, --timeout), y los tiempos de espera solicitados están limitados por --max-timeout, 600 s por defecto. Cuando un comando agota el tiempo de espera, se mata su proceso adb.
• Límites. --max-devices (50 por defecto) rechaza las llamadas que apuntan a demasiados dispositivos. La salida de cada dispositivo se trunca a --max-output caracteres.
• Comprobaciones de APK. Los archivos deben existir y terminar en .apk. --apk-dir DIR limita las instalaciones a archivos dentro de una carpeta.
• Sin credenciales y sin API de proveedores. El servidor solo llama al binario estándar adb.

Requisitos

• Node.js 18 o superior
• Android platform-tools (adb). El servidor lo busca en $ADBFLEET_ADB, luego en $ANDROID_HOME/platform-tools y luego en tu PATH.

Configuración

Claude Desktop, Cursor o cualquier cliente MCP que use el formato mcpServers:

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

Para activar los comandos de shell y limitar las instalaciones de APK a una carpeta:

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

Opciones

--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

El servidor lee el mismo inventario fleet.json que la CLI de adbfleet, desde --inventory, $ADBFLEET_INVENTORY, ./fleet.json o ~/.config/adbfleet/fleet.json. Eso permite al asistente referirse a los dispositivos por nombre, por ejemplo "serials": ["cloud-01"].

Uso con teléfonos en la nube de FoxPhone

Los teléfonos en la nube de FoxPhone son dispositivos Android que se ejecutan en la nube. Cuando el acceso ADB está habilitado, cada uno tiene un endpoint host:port, y a partir de ahí funciona como cualquier otro dispositivo de red. Aquí tienes una conversación típica con tu asistente:

1. "Conecta mis teléfonos en la nube 203.0.113.10:5555 y 203.0.113.11:5555." El asistente llama a connect_devices.
2. "¿Qué dispositivos están en línea y alguno tiene menos de 1 GB libre?" El asistente llama a list_devices y luego a device_health.
3. "Instala /home/me/builds/app-release.apk en todos ellos." El asistente llama a install_apk_on_devices con all_devices: true.
4. Con --allow-shell activado: "Abre com.example.app en los teléfonos en la nube." El asistente llama a run_shell_on_devices con monkey -p com.example.app -c android.intent.category.LAUNCHER 1.

Las direcciones anteriores son ejemplos de documentación, así que reemplázalas por los endpoints que se muestran para tus dispositivos. Los mismos pasos funcionan con cualquier dispositivo o proveedor ADB sobre TCP.

Desarrollo

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

Licencia

MIT © Foxphone LLC. Consulta LICENSE.