Skip to main content
Glama

✨ DroidMind 🤖

Python 3.13+ Licencia Estado Estilo de código Comprobación de tipo

Controlar dispositivos Android con IA a través del Protocolo de Contexto de Modelo

DroidMind es un potente puente entre los asistentes de IA y los dispositivos Android, que permite el control, la depuración y el análisis de sistemas mediante lenguaje natural. Al implementar el Protocolo de Contexto de Modelo (MCP), DroidMind permite que los modelos de IA interactúen directamente con los dispositivos Android a través de ADB de forma segura y estructurada. Al utilizarse como parte de un flujo de trabajo de codificación con agentes, DroidMind permite que el asistente compile y depure con el dispositivo directamente en el bucle.

💫 Características

  • 📱 Control de dispositivos : conéctese a dispositivos a través de USB o TCP/IP, ejecute comandos de shell, reinicie

  • 📊 Análisis del sistema : inspeccione las propiedades del dispositivo, vea información del hardware, analice los registros del sistema

  • 🔍 Acceso al sistema de archivos : explore el contenido del directorio y administre archivos en los dispositivos

  • 📷 Diagnóstico visual : captura de pantalla del dispositivo para análisis y depuración

  • 📦 Administración de aplicaciones : instalar, desinstalar, iniciar, detener y borrar datos de aplicaciones en dispositivos conectados

  • 🔄 Compatibilidad con múltiples dispositivos : controle y cambie entre múltiples dispositivos conectados

  • 👆 Automatización de la interfaz de usuario : interactúe con el dispositivo mediante toques, deslizamientos, ingreso de texto y pulsaciones de teclas.

  • 🔍 Inspección de aplicaciones : vea manifiestos de aplicaciones, preferencias compartidas y registros específicos de la aplicación

  • 🔒 Marco de seguridad : proteja los dispositivos con una validación de comandos integral

  • 💬 Integración con MCP : conexión perfecta con Claude, Cursor, Cline y más

Related MCP server: MCP Android Agent

🚀 Instalación

# Clone the repository
git clone https://github.com/hyperbliss/droidmind.git
cd droidmind

# Set up a virtual environment with UV
uv venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies with UV
uv sync

📋 Requisitos previos

  • Python 3.13 o superior

  • Dispositivo Android con depuración USB habilitada

  • ADB (Android Debug Bridge) instalado y en PATH

  • Gestor de paquetes UV (recomendado para la gestión de dependencias)

  • Para control de red: dispositivo Android con ADB sobre TCP/IP habilitado

🔮 Inicio rápido

Ejecutar el servidor DroidMind

Ejecute DroidMind como servidor para conectar asistentes de IA a través de MCP:

# Start DroidMind as a network server
droidmind --transport sse

Uso con asistentes de IA

  1. Inicie DroidMind en modo SSE:

    droidmind --transport sse
  2. Conecte su asistente de IA utilizando la URI del protocolo MCP:

    sse://localhost:4256/sse
  3. ¡La IA ahora puede controlar tus dispositivos Android a través del lenguaje natural!

🛠️ Recursos y herramientas de MCP disponibles

Recursos

  • devices://list - Lista todos los dispositivos conectados

  • device://{serial}/properties - Obtener propiedades detalladas del dispositivo

  • logs://{serial}/logcat - Obtener registros recientes del dispositivo

  • logs://{serial}/anr - Obtener rastros de aplicaciones que no responden (ANR)

  • logs://{serial}/crashes - Obtener registros de fallos de la aplicación

  • logs://{serial}/battery - Obtener estadísticas e historial de la batería

  • logs://{serial}/app/{package} - Obtener registros específicos de la aplicación

  • fs://{serial}/list/{path} - Lista el contenido del directorio en el dispositivo

  • fs://{serial}/read/{path} - Leer el contenido del archivo desde el dispositivo

  • fs://{serial}/stats/{path} - Obtener estadísticas detalladas de archivos/directorios

  • app://{serial}/{package}/manifest - Obtener el contenido de AndroidManifest.xml

  • app://{serial}/{package}/data - Lista los archivos en el directorio de datos de la aplicación

  • app://{serial}/{package}/shared_prefs - Obtener las preferencias compartidas de la aplicación

Herramientas

  • devicelist - Lista todos los dispositivos Android conectados

  • device_properties : obtiene las propiedades detalladas de un dispositivo específico

  • device_logcat : obtiene la salida reciente de logcat de un dispositivo

  • list_directory - Lista el contenido de un directorio en el dispositivo

  • connect_device - Conectarse a un dispositivo a través de TCP/IP

  • disconnect_device - Desconectarse de un dispositivo Android

  • shell_command - Ejecuta un comando de shell en el dispositivo

  • install_app - Instalar un APK en el dispositivo

  • uninstall_app - Desinstalar una aplicación del dispositivo

  • start_app - Iniciar una aplicación en el dispositivo

  • stop_app - Fuerza la detención de una aplicación en el dispositivo

  • clear_app_data - Borrar datos y caché de la aplicación

  • list_packages - Lista los paquetes instalados en el dispositivo

  • get_app_manifest : obtiene el contenido de AndroidManifest.xml para una aplicación

  • get_app_permissions - Obtener los permisos solicitados por una aplicación

  • get_app_activities - Obtener actividades definidas en una aplicación

  • get_app_info - Obtener información detallada sobre una aplicación

  • reboot_device - Reinicia el dispositivo (normal, recuperación o cargador de arranque)

  • screenshot - Obtener una captura de pantalla de un dispositivo

  • capture_bugreport : genera un informe de errores completo del dispositivo

  • dump_heap - Crea un volcado de montón desde un proceso en ejecución para el análisis de memoria

  • push_file - Sube un archivo al dispositivo

  • pull_file - Descargar un archivo desde el dispositivo

  • delete_file - Elimina un archivo o directorio del dispositivo

  • create_directory - Crea un directorio en el dispositivo

  • file_exists - Comprueba si existe un archivo en el dispositivo

  • read_file - Lee el contenido de un archivo en el dispositivo

  • write_file - Escribe contenido de texto en un archivo en el dispositivo

  • file_stats - Obtener información detallada sobre un archivo o directorio

  • tap - Toca la pantalla del dispositivo en coordenadas específicas

  • swipe - Realizar un gesto de deslizar de un punto a otro en la pantalla

  • input_text - Ingrese texto en el dispositivo como si fuera un teclado

  • press_key - Presiona una tecla de hardware o software (por ejemplo, INICIO, ATRÁS, VOLUMEN)

  • start_intent - Iniciar una actividad de la aplicación usando una intención de Android

📊 Ejemplos de consultas del Asistente de IA

Con un asistente de IA conectado a DroidMind, prueba estas consultas:

  • "Enumera todos los dispositivos Android conectados y muéstrame sus propiedades"

  • "Conéctate a mi teléfono en 192.168.1.100 y comprueba el estado de la batería"

  • "Toma una captura de pantalla de mi Pixel y muéstrame qué hay en pantalla actualmente"

  • "Comprobar el espacio de almacenamiento disponible en mi dispositivo"

  • "Muéstrame los rastros de ANR y los registros de fallos de mi dispositivo"

  • "Mira los registros recientes y dime si hay algún error"

  • "Instala este archivo APK en mi dispositivo y dime si se instaló correctamente"

  • "Muéstrame una lista de todas las aplicaciones instaladas en mi teléfono"

  • "Reiniciar mi dispositivo en modo de recuperación"

  • "¿Qué versión de Android tiene mi teléfono?"

  • "Comprueba si mi dispositivo está rooteado e indícame su nivel de parche de seguridad"

  • "Muéstrame el archivo de manifiesto de com.android.settings"

  • "Comprueba las preferencias compartidas de mi aplicación"

  • Pulsa el icono de Configuración en las coordenadas 500,1000.

  • Desliza el dedo hacia abajo desde la parte superior de la pantalla para abrir la barra de notificaciones.

  • "Ingrese mi contraseña en el campo de texto actual"

  • "Presione el botón Atrás tres veces para volver a la pantalla de inicio"

  • "Abre la aplicación Configuración iniciando el paquete com.android.settings"

🔒 Funciones de seguridad

DroidMind incluye un marco de seguridad integral para proteger sus dispositivos y al mismo tiempo permitir que los asistentes de IA sean expresivos:

  • Validación de comandos : todos los comandos de shell se validan con una lista de comandos seguros permitidos

  • Evaluación de riesgos : los comandos se clasifican por nivel de riesgo (SEGURO, BAJO, MEDIO, ALTO, CRÍTICO)

  • Sanitización de comandos : la entrada se desinfecta para evitar ataques de inyección de comandos

  • Rutas protegidas : los directorios del sistema y las rutas críticas están protegidos contra modificaciones

  • Registro completo : todos los comandos se registran con su nivel de riesgo para auditoría.

  • Detección de patrones sospechosos : se bloquean los comandos con patrones potencialmente peligrosos

  • Seguridad de comandos ADB : manejo especial para comandos específicos de ADB con validación asíncrona adecuada

El sistema de seguridad está diseñado para ser lo suficientemente permisivo como para permitir operaciones comunes y, al mismo tiempo, prevenir acciones destructivas. Los comandos de alto riesgo mostrarán advertencias a los usuarios antes de su ejecución, y las operaciones críticas se bloquearán por completo sin necesidad de una anulación explícita.

💻 Desarrollo

DroidMind utiliza UV para la gestión de dependencias y los flujos de trabajo de desarrollo. UV es un gestor y solucionador de paquetes de Python rápido y fiable.

# Update dependencies
uv sync

# Run tests
pytest

# Run linting
ruff check .

# Run type checking
mypy .

🤝 Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

  1. Bifurcar el repositorio

  2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )

  3. Configura tu entorno de desarrollo con UV

  4. Realiza tus cambios

  5. Ejecutar pruebas y linting

  6. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

  7. Empujar a la rama ( git push origin feature/amazing-feature )

  8. Abrir una solicitud de extracción

📝 Licencia

Este proyecto está licenciado bajo la licencia Apache: consulte el archivo de LICENCIA para obtener más detalles.


Creado por Stefanie Jane 🌠

Si te resulta útil DroidMind, cómprame un Monster Ultra Violet ⚡️

Available Tools

8 tools
android-appA

Perform various application management operations on an Android device.

This single tool consolidates various app-related actions. The 'action' parameter determines the operation.

Args: serial: Device serial number. action: The specific app operation to perform. ctx: MCP Context for logging and interaction. package (Optional[str]): Package name for the target application. Required by most actions. apk_path (Optional[str]): Path to the APK file (local to the server). Used by install_app. reinstall (Optional[bool]): Whether to reinstall if app exists. Used by install_app. grant_permissions (Optional[bool]): Whether to grant all requested permissions. Used by install_app. keep_data (Optional[bool]): Whether to keep app data and cache directories. Used by uninstall_app. activity (Optional[str]): Optional activity name to start. Used by start_app. extras (Optional[dict[str, str]]): Optional intent extras. Used by start_intent. include_system_apps (Optional[bool]): Whether to include system apps. Used by list_packages. include_app_name (Optional[bool]): Whether to include app labels (best-effort). Used by list_packages. include_apk_path (Optional[bool]): Whether to include APK paths. Used by list_packages. max_packages (Optional[int]): Max packages to return. Used by list_packages.

Returns: A string message indicating the result or status of the operation.


Available Actions and their specific argument usage:

  1. action="install_app"

    • Requires: apk_path

    • Optional: reinstall, grant_permissions

  2. action="uninstall_app"

    • Requires: package

    • Optional: keep_data

  3. action="start_app"

    • Requires: package

    • Optional: activity 3b. action="start_intent"

    • Requires: package, activity

    • Optional: extras

  4. action="stop_app"

    • Requires: package

  5. action="clear_app_data"

    • Requires: package

  6. action="list_packages"

    • Optional: include_system_apps, include_app_name, include_apk_path, max_packages

  7. action="get_app_manifest"

    • Requires: package

  8. action="get_app_permissions"

    • Requires: package

  9. action="get_app_activities"

    • Requires: package

  10. action="get_app_info"

    • Requires: package


Inputs: serial (required), action (required), package, apk_path, +9 more. Returns: result

android-deviceA

Perform various device management operations on Android devices.

This single tool consolidates various device-related actions. The 'action' parameter determines the operation.

Args: action: The specific device operation to perform. ctx: MCP Context for logging and interaction. serial (Optional[str]): Device serial number. Required by most actions except connect/list. ip_address (Optional[str]): IP address for 'connect_device' action. port (Optional[int]): Port for 'connect_device' action (default: 5555). mode (Optional[str]): Reboot mode for 'reboot_device' action (default: "normal").

Returns: A string message indicating the result or status of the operation.


Available Actions and their specific argument usage:

  1. action="list_devices"

    • No specific arguments required beyond ctx.

  2. action="connect_device"

    • Requires: ip_address

    • Optional: port

  3. action="disconnect_device"

    • Requires: serial

  4. action="reboot_device"

    • Requires: serial

    • Optional: mode (e.g., "normal", "recovery", "bootloader")

  5. action="device_properties"

    • Requires: serial


Inputs: action (required), serial, ip_address, port, +1 more. Returns: result

android-diagA

Perform diagnostic operations like capturing bug reports or heap dumps.

Args: ctx: MCP Context. serial: Device serial number. action: The diagnostic action to perform. output_path: Optional. Path to save the output file. For bugreport: host path for adb to write the .zip. If empty, a temp file is used & summarized. For dump_heap: local path to save the .hprof. If empty, a temp file is used. include_screenshots: For CAPTURE_BUGREPORT. Default True. package_or_pid: For DUMP_HEAP. App package name or process ID. native: For DUMP_HEAP. True for native (C/C++) heap, False for Java. Default False. timeout_seconds: Max time for the operation. If 0, action-specific defaults are used (bugreport: 300s, dump_heap: 120s).

Returns: A string message indicating the result or path to the output.

Inputs: serial (required), action (required), output_path, include_screenshots, +3 more. Returns: result

android-fileA

Perform file and directory operations on an Android device.

This single tool consolidates various file system actions. The 'action' parameter determines the operation.

Args: serial: Device serial number. action: The specific file operation to perform. See available actions below. ctx: MCP Context for logging and interaction. path (Optional[str]): General path argument on the device. Used by: list_directory, delete_file, create_directory, file_exists, file_stats. Can also be used by read_file and write_file as an alternative to 'device_path'. local_path (Optional[str]): Path on the DroidMind server machine. Used by: push_file (source), pull_file (destination). device_path (Optional[str]): Path on the Android device. Used by: push_file (destination), pull_file (source), read_file (source), write_file (destination). If 'path' is also provided for read/write, 'device_path' takes precedence. content (Optional[str]): Text content to write. Used by: write_file. max_size (Optional[int]): Maximum file size in bytes for read_file (default: 100KB). Used by: read_file.

Returns: Union[str, bool]: A string message indicating the result or status for most actions. Returns a boolean for the 'file_exists' action.


Available Actions and their specific argument usage:

  1. action="list_directory": Lists contents of a directory.

    • Requires: path (directory path on device).

    • Returns: Formatted string of directory contents.

  2. action="push_file": Uploads a file from the local server to the device.

    • Requires: local_path (source on server), device_path (destination on device).

    • Returns: String message confirming upload.

  3. action="pull_file": Downloads a file from the device to the local server.

    • Requires: device_path (source on device), local_path (destination on server).

    • Returns: String message confirming download.

  4. action="delete_file": Deletes a file or directory from the device.

    • Requires: path (path to delete on device).

    • Returns: String message confirming deletion.

  5. action="create_directory": Creates a directory on the device.

    • Requires: path (directory path to create on device).

    • Returns: String message confirming creation.

  6. action="file_exists": Checks if a file or directory exists on the device.

    • Requires: path (path to check on device).

    • Returns: True if exists, False otherwise.

  7. action="read_file": Reads the contents of a file from the device.

    • Requires: device_path (or path) for the file on device.

    • Optional: max_size (defaults to 100KB).

    • Returns: String containing file contents or error message.

  8. action="write_file": Writes text content to a file on the device.

    • Requires: device_path (or path) for the file on device, content (text to write).

    • Returns: String message confirming write.

  9. action="file_stats": Gets detailed statistics for a file or directory.

    • Requires: path (path on device).

    • Returns: Markdown-formatted string of file/directory statistics.


Inputs: serial (required), action (required), path, local_path, +3 more. Returns: result

android-logA

Perform various log retrieval operations on an Android device.

This single tool consolidates various log-related actions. The 'action' parameter determines the operation.

Args: serial: Device serial number. action: The specific log operation to perform. ctx: MCP Context for logging and interaction. package (Optional[str]): Package name for get_app_logs action. lines (int): Number of lines to fetch for logcat actions (default: 1000). filter_expr (Optional[str]): Logcat filter expression for get_device_logcat. buffer (Optional[str]): Logcat buffer for get_device_logcat (default: "main"). format_type (Optional[str]): Logcat output format for get_device_logcat (default: "threadtime"). max_size (Optional[int]): Max output size for get_device_logcat (default: 100KB).

Returns: A string message containing the requested logs or status.


Available Actions and their specific argument usage:

  1. action="get_device_logcat"

    • Optional: lines, filter_expr, buffer, format_type, max_size.

  2. action="get_app_logs"

    • Requires: package.

    • Optional: lines.

  3. action="get_anr_logs"

    • No specific arguments beyond serial and ctx.

  4. action="get_crash_logs"

    • No specific arguments beyond serial and ctx.

  5. action="get_battery_stats"

    • No specific arguments beyond serial and ctx.


Inputs: serial (required), action (required), package, lines, +4 more. Returns: result

android-screenshotA

Get a screenshot from a device.

Args: serial: Device serial number ctx: MCP context quality: JPEG quality (1-100, lower means smaller file size)

Returns: The device screenshot as an image

Inputs: serial (required), quality.

android-shellA

Run a shell command on the device.

Args: serial: Device serial number command: Shell command to run max_lines: Maximum lines of output to return (default: 1000) Use positive numbers for first N lines, negative for last N lines Set to None for unlimited (not recommended for large outputs) max_size: Maximum output size in characters (default: 100000) Limits total response size regardless of line count

Returns: Command output

Inputs: serial (required), command (required), max_lines, max_size. Returns: result

android-uiB

Perform various UI interaction operations on an Android device.

Args: ctx: MCP Context. serial: Device serial number. action: The UI action to perform. x: X coordinate (for tap). y: Y coordinate (for tap). start_x: Starting X coordinate (for swipe). start_y: Starting Y coordinate (for swipe). end_x: Ending X coordinate (for swipe). end_y: Ending Y coordinate (for swipe). duration_ms: Duration of the swipe in milliseconds (default: 300). text: Text to input (for input_text). keycode: Android keycode to press (for press_key). package: Package name (for start_intent). activity: Activity name (for start_intent). extras: Optional intent extras (for start_intent).

Returns: A string message indicating the result of the operation.

Inputs: serial (required), action (required), x, y, +10 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation3/5

    The top-level tools are clearly categorized, but the internal actions within each mega-tool can overlap (e.g., start_intent appears in both android-app and android-ui), causing potential ambiguity for an agent. Additionally, the bundling of many operations under one tool name makes it less obvious which tool handles a specific action.

    Naming Consistency5/5

    All tool names follow a consistent 'android-<category>' pattern, and internal actions use a uniform snake_case style. The naming is predictable and readable across the entire server.

    Tool Count4/5

    With 8 tools, the count is reasonable for an Android device management server. However, the bundling of many actions into each tool makes the surface feel slightly under-tooled, though still within the effective range.

    Completeness4/5

    The tool set covers major areas: app management, device control, diagnostics, file operations, logs, screenshots, shell, and UI. Some gaps exist (e.g., network or settings management), but the core workflows for common Android tasks are well addressed.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI agents to control and automate Android devices through natural language, supporting actions like app management, UI interactions, and device monitoring.
      60
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A MCP server that enables AI assistants to control Android devices via ADB, supporting device info, screen control, input simulation, app management, shell execution, file transfer, and UI parsing.
      20
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that wraps Android ADB functionality into AI assistant tools, enabling device management, shell execution, file operations, app management, media capture, and log analysis via natural language.
      23 npm
      3
      MIT