ADB Automation MCP

adb-automation-mcp

Un servidor MCP que expone las capacidades de Android Debug Bridge (ADB) como herramientas y recursos tipados y documentados. Consulta Arquitectura para ver cómo está organizado el sistema.

Requisitos

• Python ≥ 3.10
• uv
• Android platform-tools (adb) — solo se necesitan para el backend real; el backend simulado (abajo) no requiere nada relacionado con dispositivos instalado.

Cómo ejecutarlo

uv sync
uv run adb-automation-mcp

Por defecto, esto se comunica con el binario adb que se encuentra en PATH. Configúralo con variables de entorno:

Variable de entorno	Propósito	Valor predeterminado
ADB_AUTOMATION_BACKEND=fake	Usa el backend simulado determinista en lugar de adb real — no se necesita binario adb ni dispositivo	sin definir (backend real)
ADB_AUTOMATION_ADB_PATH	Ruta explícita al binario adb	sin definir (se resuelve mediante PATH)
ADB_AUTOMATION_TIMEOUT_S	Tiempo de espera por comando, en segundos	10
ADB_AUTOMATION_ALLOW_DESTRUCTIVE=1	Optar por las herramientas de la categoría destructive (p. ej., uninstall_package, remove_user, restart_adbd_as_root)	sin definir (denegadas por defecto)
ADB_AUTOMATION_LOCAL_ROOT	La carpeta en esta máquina donde las herramientas de guardado de archivos pueden escribir	sin definir — esas herramientas se niegan a escribir en cualquier lugar hasta que se defina

ADB_AUTOMATION_ADB_PATH importa más de lo que parece: un cliente MCP (Claude Code, Claude Desktop,...) lanza este servidor con un entorno mínimo que normalmente no incluye las personalizaciones de PATH de tu shell, así que el hecho de que adb se resuelva correctamente en tu terminal no significa que se resolverá dentro del servidor lanzado. Define la ruta explícitamente al integrarlo con un cliente (consulta Integraciones).

# real device/emulator, explicit adb path
ADB_AUTOMATION_ADB_PATH=/path/to/platform-tools/adb uv run adb-automation-mcp

# deterministic fake backend, no adb required
ADB_AUTOMATION_BACKEND=fake uv run adb-automation-mcp

Dónde se guardan los archivos guardados (ADB_AUTOMATION_LOCAL_ROOT)

Algunas herramientas guardan un archivo en esta máquina: pull_file (copia un archivo del dispositivo), stop_log_session (guarda un registro capturado) y take_screenshot (guarda el PNG y devuelve su ruta — no devuelve los bytes de la imagen en línea). ADB_AUTOMATION_LOCAL_ROOT es la única carpeta donde estas herramientas pueden escribir — no hay ubicación alternativa, por lo que se niegan a ejecutarse hasta que se defina.

pull_file y stop_log_session aceptan un argumento local_path, una ruta dentro de esa carpeta. Con ADB_AUTOMATION_LOCAL_ROOT=/home/you/adb-downloads definido:

• pull_file(..., local_path="ui-dump.xml") escribe en /home/you/adb-downloads/ui-dump.xml
• stop_log_session(..., local_path="session1.log") escribe en /home/you/adb-downloads/session1.log
• take_screenshot(...) escribe en /home/you/adb-downloads/screenshots/screenshot-<serial>-<timestamp>.png (o screenshots/<filename>.png cuando se proporciona filename=) y devuelve esa ruta absoluta

Un local_path que intente escapar de esa carpeta — ../elsewhere, o una ruta absoluta que apunte a otro lugar — se rechaza en lugar de escribirse en cualquier parte.

ADB_AUTOMATION_LOCAL_ROOT=/home/you/adb-downloads uv run adb-automation-mcp

Configuración del cliente MCP

Agrega esto al mcp.json de tu cliente (p. ej., la configuración de Claude Desktop, o el .mcp.json de un proyecto de Claude Code — consulta Integraciones). Otros clientes usan una forma similar de command / args / env pero con una clave de nivel superior diferente (el .vscode/mcp.json de VS Code Copilot, por ejemplo, usa servers en lugar de mcpServers) — consulta la documentación de MCP de tu propio cliente para conocer el envoltorio exacto. Cada variable de entorno de la tabla anterior es opcional; se muestra aquí con valores de ejemplo:

{
  "mcpServers": {
    "adb-automation-mcp": {
      "command": "uvx",
      "args": ["adb-automation-mcp"],
      "env": {
        "ADB_AUTOMATION_ADB_PATH": "/path/to/platform-tools/adb",
        "ADB_AUTOMATION_TIMEOUT_S": "10",
        "ADB_AUTOMATION_ALLOW_DESTRUCTIVE": "1",
        "ADB_AUTOMATION_LOCAL_ROOT": "/path/to/local/root"
      }
    }
  }
}

Herramientas disponibles

111 herramientas. Consulta la Referencia de herramientas para ver la firma completa, el docstring y un ejemplo práctico de cada herramienta — generada directamente desde el código fuente, por lo que no puede desincronizarse de lo que el servidor realmente expone. El README tiene la lista completa por módulo.

Pruebas

uv run pytest        # registry contract, unit, and e2e tests
uv run mypy src       # strict type checking
uv run ruff check .   # lint

Licencia

MIT