DroidMind

Features

• Device Control - Connect to devices over USB or TCP/IP, run shell commands, reboot

• System Analysis - Inspect device properties, view hardware info, analyze system logs

• File System Access - Browse directory contents and manage files on devices

• Visual Diagnostics - Capture device screenshots for analysis and debugging

• App Management - Install, uninstall, start, stop, and clear app data on connected devices

• Multi-Device Support - Control and switch between multiple connected devices

• UI Automation - Interact with the device through taps, swipes, text input, and key presses

• App Inspection - View app manifests, shared preferences, and app-specific logs

• Security Framework - Protect devices with comprehensive command validation

• MCP Integration - Seamless connection to Claude, Cursor, Cline, and more

Installation

Prerequisites

• Python 3.13 or higher

• Android device with USB debugging enabled

• ADB (Android Debug Bridge) installed and in PATH

• UV package manager (recommended for dependency management)

• For network control: Android device with ADB over TCP/IP enabled

Quick Start

Run the DroidMind server

Using with AI Assistants

1. Start DroidMind in SSE mode:

2. Connect your AI assistant using the MCP protocol URI:

3. The AI can now control your Android devices through natural language!

Available MCP Resources and Tools

Resources

• devices://list - List all connected devices

• device://{serial}/properties - Get detailed device properties

• logs://{serial}/logcat - Get recent logs from the device

• logs://{serial}/anr - Get Application Not Responding (ANR) traces

• logs://{serial}/crashes - Get application crash logs

• logs://{serial}/battery - Get battery statistics and history

• logs://{serial}/app/{package} - Get application-specific logs

• fs://{serial}/list/{path} - List directory contents on the device

• fs://{serial}/read/{path} - Read file contents from the device

• fs://{serial}/stats/{path} - Get detailed file/directory statistics

• app://{serial}/{package}/manifest - Get AndroidManifest.xml contents

• app://{serial}/{package}/data - List files in the app's data directory

• app://{serial}/{package}/shared_prefs - Get app's shared preferences

Tools

• devicelist - List all connected Android devices

• device_properties - Get detailed properties of a specific device

• device_logcat - Get recent logcat output from a device

• list_directory - List contents of a directory on the device

• connect_device - Connect to a device over TCP/IP

• disconnect_device - Disconnect from an Android device

• shell_command - Run a shell command on the device

• install_app - Install an APK on the device

• uninstall_app - Uninstall an app from the device

• start_app - Start an app on the device

• stop_app - Force stop an app on the device

• clear_app_data - Clear app data and cache

• list_packages - List installed packages on the device

• get_app_manifest - Get AndroidManifest.xml contents for an app

• get_app_permissions - Get permissions requested by an app

• get_app_activities - Get activities defined in an app

• get_app_info - Get detailed information about an app

• reboot_device - Reboot the device (normal, recovery, or bootloader)

• screenshot - Get a screenshot from a device

• capture_bugreport - Generate a comprehensive bug report from the device

• dump_heap - Create a heap dump from a running process for memory analysis

• push_file - Upload a file to the device

• pull_file - Download a file from the device

• delete_file - Delete a file or directory from the device

• create_directory - Create a directory on the device

• file_exists - Check if a file exists on the device

• read_file - Read the contents of a file on the device

• write_file - Write text content to a file on the device

• file_stats - Get detailed information about a file or directory

• tap - Tap on the device screen at specific coordinates

• swipe - Perform a swipe gesture from one point to another on the screen

• input_text - Input text on the device as if from a keyboard

• press_key - Press a hardware or software key (e.g., HOME, BACK, VOLUME)

• start_intent - Start an app activity using an Android intent

Example AI Assistant Queries

• "List all connected Android devices and show me their properties"

• "Connect to my phone at 192.168.1.100 and check its battery status"

• "Take a screenshot of my Pixel and show me what's currently on screen"

• "Check the available storage space on my device"

• "Show me the ANR traces and crash logs from my device"

• "Look at recent logs and tell me if there are any errors"

• "Install this APK file on my device and tell me if it was successful"

• "Show me a list of all installed apps on my phone"

• "Reboot my device into recovery mode"

• "What Android version is my phone running?"

• "Check if my device is rooted and tell me its security patch level"

• "Show me the manifest file for com.android.settings"

• "Check the shared preferences for my app"

• "Tap on the Settings icon at coordinates 500,1000"

• "Swipe down from the top of the screen to open the notification shade"

• "Input my password into the current text field"

• "Press the back button three times to return to the home screen"

• "Open the Settings app by starting the com.android.settings package"

Security Features

• Command Validation: All shell commands are validated against an allowlist of safe commands

• Risk Assessment: Commands are categorized by risk level (SAFE, LOW, MEDIUM, HIGH, CRITICAL)

• Command Sanitization: Input is sanitized to prevent command injection attacks

• Protected Paths: System directories and critical paths are protected from modification

• Comprehensive Logging: All commands are logged with their risk level for auditing

• Suspicious Pattern Detection: Commands with potentially dangerous patterns are blocked

• ADB Command Security: Special handling for ADB-specific commands with proper async validation

Development

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Set up your development environment with UV

4. Make your changes

5. Run tests and linting

6. Commit your changes (git commit -m 'Add some amazing feature')

7. Push to the branch (git push origin feature/amazing-feature)

8. Open a Pull Request

License

DroidMind

Features

• Device Control - Connect to devices over USB or TCP/IP, run shell commands, reboot

• System Analysis - Inspect device properties, view hardware info, analyze system logs

• File System Access - Browse directory contents and manage files on devices

• Visual Diagnostics - Capture device screenshots for analysis and debugging

• App Management - Install, uninstall, start, stop, and clear app data on connected devices

• Multi-Device Support - Control and switch between multiple connected devices

• UI Automation - Interact with the device through taps, swipes, text input, and key presses

• App Inspection - View app manifests, shared preferences, and app-specific logs

• Security Framework - Protect devices with comprehensive command validation

• MCP Integration - Seamless connection to Claude, Cursor, Cline, and more

Installation

Prerequisites

• Python 3.13 or higher

• Android device with USB debugging enabled

• ADB (Android Debug Bridge) installed and in PATH

• UV package manager (recommended for dependency management)

• For network control: Android device with ADB over TCP/IP enabled

Quick Start

Run the DroidMind server

Using with AI Assistants

1. Start DroidMind in SSE mode:

2. Connect your AI assistant using the MCP protocol URI:

3. The AI can now control your Android devices through natural language!

Available MCP Resources and Tools

Resources

• devices://list - List all connected devices

• device://{serial}/properties - Get detailed device properties

• logs://{serial}/logcat - Get recent logs from the device

• logs://{serial}/anr - Get Application Not Responding (ANR) traces

• logs://{serial}/crashes - Get application crash logs

• logs://{serial}/battery - Get battery statistics and history

• logs://{serial}/app/{package} - Get application-specific logs

• fs://{serial}/list/{path} - List directory contents on the device

• fs://{serial}/read/{path} - Read file contents from the device

• fs://{serial}/stats/{path} - Get detailed file/directory statistics

• app://{serial}/{package}/manifest - Get AndroidManifest.xml contents

• app://{serial}/{package}/data - List files in the app's data directory

• app://{serial}/{package}/shared_prefs - Get app's shared preferences

Tools

• devicelist - List all connected Android devices

• device_properties - Get detailed properties of a specific device

• device_logcat - Get recent logcat output from a device

• list_directory - List contents of a directory on the device

• connect_device - Connect to a device over TCP/IP

• disconnect_device - Disconnect from an Android device

• shell_command - Run a shell command on the device

• install_app - Install an APK on the device

• uninstall_app - Uninstall an app from the device

• start_app - Start an app on the device

• stop_app - Force stop an app on the device

• clear_app_data - Clear app data and cache

• list_packages - List installed packages on the device

• get_app_manifest - Get AndroidManifest.xml contents for an app

• get_app_permissions - Get permissions requested by an app

• get_app_activities - Get activities defined in an app

• get_app_info - Get detailed information about an app

• reboot_device - Reboot the device (normal, recovery, or bootloader)

• screenshot - Get a screenshot from a device

• capture_bugreport - Generate a comprehensive bug report from the device

• dump_heap - Create a heap dump from a running process for memory analysis

• push_file - Upload a file to the device

• pull_file - Download a file from the device

• delete_file - Delete a file or directory from the device

• create_directory - Create a directory on the device

• file_exists - Check if a file exists on the device

• read_file - Read the contents of a file on the device

• write_file - Write text content to a file on the device

• file_stats - Get detailed information about a file or directory

• tap - Tap on the device screen at specific coordinates

• swipe - Perform a swipe gesture from one point to another on the screen

• input_text - Input text on the device as if from a keyboard

• press_key - Press a hardware or software key (e.g., HOME, BACK, VOLUME)

• start_intent - Start an app activity using an Android intent

Example AI Assistant Queries

• "List all connected Android devices and show me their properties"

• "Connect to my phone at 192.168.1.100 and check its battery status"

• "Take a screenshot of my Pixel and show me what's currently on screen"

• "Check the available storage space on my device"

• "Show me the ANR traces and crash logs from my device"

• "Look at recent logs and tell me if there are any errors"

• "Install this APK file on my device and tell me if it was successful"

• "Show me a list of all installed apps on my phone"

• "Reboot my device into recovery mode"

• "What Android version is my phone running?"

• "Check if my device is rooted and tell me its security patch level"

• "Show me the manifest file for com.android.settings"

• "Check the shared preferences for my app"

• "Tap on the Settings icon at coordinates 500,1000"

• "Swipe down from the top of the screen to open the notification shade"

• "Input my password into the current text field"

• "Press the back button three times to return to the home screen"

• "Open the Settings app by starting the com.android.settings package"

Security Features

• Command Validation: All shell commands are validated against an allowlist of safe commands

• Risk Assessment: Commands are categorized by risk level (SAFE, LOW, MEDIUM, HIGH, CRITICAL)

• Command Sanitization: Input is sanitized to prevent command injection attacks

• Protected Paths: System directories and critical paths are protected from modification

• Comprehensive Logging: All commands are logged with their risk level for auditing

• Suspicious Pattern Detection: Commands with potentially dangerous patterns are blocked

• ADB Command Security: Special handling for ADB-specific commands with proper async validation

Development

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Set up your development environment with UV

4. Make your changes

5. Run tests and linting

6. Commit your changes (git commit -m 'Add some amazing feature')

7. Push to the branch (git push origin feature/amazing-feature)

8. Open a Pull Request

License