adb-mcp

---

Inicia un AVD, toma capturas de pantalla, lee la jerarquía de la interfaz, toca/desliza/escribe, establece un bloqueo de dispositivo, lee logcat, ejecuta compilaciones y pruebas de Gradle. 78 herramientas, desde Claude Code, Cursor, VS Code o cualquier cliente MCP a través de stdio.

Es la contraparte de Android para XcodeBuildMCP, construido sobre el Go MCP SDK oficial.

Android es una marca comercial de Google LLC. adb-mcp es una herramienta independiente y no oficial construida para Android y no está afiliada, patrocinada ni respaldada por Google. El robot de Android arriba se reproduce/modifica a partir de un trabajo creado y compartido por Google y se usa según los términos descritos en la Licencia de Atribución Creative Commons 3.0.

Por qué

Controlar Android manualmente significa un largo manual de comandos adb en bruto, y es fácil equivocarse (coordenadas de toque obsoletas, capturas de pantalla corruptas por CRLF, olvidar exec-out, adivinar coordenadas a partir de una imagen reducida). Este servidor incorpora ese conocimiento en sus herramientas, para que el agente no tenga que reaprenderlo:

• Las capturas de pantalla usan exec-out screencap (sin corrupción por CRLF) y se reducen automáticamente para que el lector de imágenes las acepte.
• describe_ui devuelve el centro de cada elemento en píxeles reales del dispositivo (para que los toques aterricen donde quieres, sin adivinar a partir de la imagen) y reintenta por sí solo el fallo transitorio de "no se pudo obtener el estado inactivo".

El flujo de trabajo en sí se entrega como recursos legibles que el agente puede consultar a mitad de tarea (el bucle observar→actuar, manejo de PIN/bloqueo nativo, triaje de fallos, ver abajo) en lugar de reaprenderlos en cada sesión.

Primeros pasos

1. Requisitos previos

• SDK de Android con platform-tools (adb) y emulator. El servidor lo encuentra a través de $ANDROID_HOME / $ANDROID_SDK_ROOT, o si no, el valor predeterminado de la plataforma (~/Library/Android/sdk en macOS). Si tu cliente MCP inicia el servidor sin esas variables configuradas, pasa --sdk /path/to/sdk en el args de la configuración del cliente (el servidor lo exporta, para que Gradle también encuentre el SDK). doctor imprime la ubicación que resolvió.
• Al menos un AVD (crea uno en el Administrador de dispositivos de Android Studio).

Go no es necesario: los lanzamientos incluyen binarios precompilados, y solo se necesita para compilar desde el código fuente.

2. Instalación

En macOS/Linux:

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

El script (install.sh) elige el archivo correcto para tu sistema operativo/arquitectura, verifica su SHA-256 contra el checksums.txt del lanzamiento e instala en ~/.local/bin (anula con BIN_DIR=...; fija una versión con VERSION=v0.17.0).

¿Prefieres descargar el binario tú mismo? El archivo de cada plataforma (macOS, Linux y Windows, amd64 y arm64) está en la página de Lanzamientos, cada uno con una suma de verificación en checksums.txt. En Windows, descarga el zip windows_amd64 o windows_arm64 y coloca adb-mcp.exe en algún lugar de tu PATH.

Una vez instalado, mantente actualizado con el actualizador integrado. Descarga el último lanzamiento, verifica su suma de verificación y reemplaza el binario en su lugar:

adb-mcp update

El registro a continuación inicia el servidor por el nombre simple adb-mcp, por lo que debe estar en tu $PATH (which adb-mcp debería resolverse; el instalador advierte si ~/.local/bin no está en él). De lo contrario, apunta el cliente a la ruta absoluta del binario.

3. Regístrate con tu cliente MCP

Claude Code:

claude mcp add adb -- adb-mcp

(Cuando trabajes dentro de este repositorio, el .mcp.json incluido se detecta automáticamente, sin necesidad de registro).

Cursor / VS Code: instalación con un clic (asume que adb-mcp está en tu PATH desde el paso 2):

Cualquier otro cliente (Windsurf, Codex, …): ejecuta adb-mcp a través de stdio. La forma habitual de configuración:

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

Para confirmar que está conectado, pide a tu agente que "inicie un emulador y tome una captura de pantalla".

Desde el código fuente (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

Herramientas

78 herramientas en diez áreas. Cada herramienta orientada al dispositivo acepta un serial opcional (adb -s). Omítelo con un dispositivo conectado, o pasa uno de list_devices con varios. Referencia completa: docs/TOOLS.md.

• Emulador / dispositivo: iniciar, listar, esperar a que arranque, apagar, conectar por Wi-Fi, adb_reverse reenvío de puertos (¡Metro!)
• Observar: screenshot para ver (funciona en plegables con varias pantallas, elige un panel con display), describe_ui para centros de elementos en píxeles reales, con la ventana superior enfocada (detecta un aviso biométrico, o la aplicación equivocada, que oculte tu objetivo mediante package opcional), modos filter/query/compact, y un contador de nodos ocultos para que la ausencia sea confiable
• Interactuar: tocar, tap_on_text/tap_element (direccionados por id), deslizar, arrastrar, mantener presionado, escribir, combinaciones de teclas, teclados PIN, wait, run_sequence (pasos por lotes + guardas en una sola llamada, lo que evita que los flujos de temporizadores nativos se vean perturbados por viajes de ida y vuelta por paso); verify_change opcional te dice si un toque/tecla realmente cambió la interfaz; via_accessibility opcional en tap_on_text/tap_element (EXPERIMENTAL) envía un clic de accesibilidad real para vistas nativas que un toque por coordenadas no puede alcanzar, ver bridge/README.md
• Bloqueo / Almacén de claves / Biometría: establecer/limpiar una pantalla de bloqueo segura, verificar el estado del bloqueo, has_biometric_enrolled + fingerprint_touch/finger_remove para satisfacer un BiometricPrompt en el emulador
• Controles extendidos (emulador): send_sms (OTP/2FA), phone_call, set_battery (también funciona en dispositivos reales a través de dumpsys), cellular (itinerancia/señal débil/limitada), set_sensor (acelerómetro/luz/…), rotate_screen, avd_snapshot, controlando el panel solo de consola del emulador que describe_ui no puede ver
• Ciclo de vida de la aplicación: instalar/desinstalar, iniciar/detener, app_state (pid(s) en ejecución + paquete Metro-vs-incorporado), launch_dev_client (compilación de desarrollo Expo → Metro, omitiendo el Dev Launcher), reload_app/open_dev_menu, borrar datos, permisos, enlaces profundos, enviar/recibir archivos, last_crash
• Registros y captura: logcat de una sola vez o en streaming (filtros de subcadena/prioridad/etiqueta, ventana de tiempo since, redact opcional para enmascarar tokens/contraseñas/claves API antes de la salida), clear_logcat, last_crash, grabación de pantalla
• Entorno y diagnóstico: modo oscuro, ubicación simulada, barra de estado limpia, stay_awake (detén una pantalla que se apaga por doze y arruina tus capturas), doctor
• Compilación y prueba de Gradle: assembleDebug, pruebas unitarias, pruebas instrumentadas, cobertura de pruebas unitarias JVM a través de JaCoCo (get_coverage_report/get_file_coverage), descubrimiento de tareas + variantes + módulos (list_gradle_variants/list_gradle_projects), build_and_run de una sola vez
• Valores predeterminados de sesión: fija project_dir/serial una vez (session_set_defaults) para que un proyecto de varios módulos/varias variantes o una sesión de varios dispositivos no necesite repetirlos en cada llamada

El conocimiento práctico en sí se entrega como cinco recursos MCP (android://guide/*) que el cliente puede listar y leer. Ver docs/TOOLS.md para las URI, o ve directamente a android://guide/driving para el bucle central a continuación.

El bucle central

observar → localizar → actuar → re-observar. screenshot para ver, describe_ui para obtener centros en píxeles reales, tap/tap_on_text/swipe/input_text para actuar, y luego screenshot de nuevo para confirmar. Lee android://guide/driving para el bucle completo y los errores comunes que desperdician turnos.

Desarrollo

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

Estructura:

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

Las dependencias apuntan solo hacia adentro (tools → adb, gradle, uiauto → sdk), y cada adaptador internal/tools/<domain>.go refleja un archivo de ejecución del mismo nombre (los comandos del dispositivo son métodos adb.Client). Mapa completo, gráfico de paquetes y reglas para agregar una herramienta: ARCHITECTURE.md.

Documentación

• adb-mcp.com: página de inicio
• docs/TOOLS.md: referencia completa herramienta por herramienta y los recursos de guía
• ARCHITECTURE.md: la convención de espejo, la estructura de paquetes y cómo agregar una herramienta
• docs/CHANGELOG.md: trabajo publicado, más reciente primero
• docs/BACKLOG.md: ideas abiertas y brechas de paridad con XcodeBuildMCP

Contribuciones

Ver CONTRIBUTING.md para la configuración y las convenciones. ¿Encontraste un problema de seguridad? Consulta SECURITY.md en lugar de abrir un problema público. Licenciado bajo MIT.