✨ DroidMind 🤖

Control Android devices with AI through the Model Context Protocol

</div>

DroidMind is a powerful bridge between AI assistants and Android devices, enabling control, debugging, and system analysis through natural language. By implementing the Model Context Protocol (MCP), DroidMind allows AI models to directly interact with Android devices via ADB in a secure, structured way. When used as part of an agentic coding workflow, DroidMind can enable your assistant to build and debug with your device directly in the loop.

💫 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
🌈 NeonGlam Console - Enjoy an aesthetic terminal experience with cyberpunk vibes
💬 MCP Integration - Seamless connection to Claude, Cursor, Cline, and more

🚀 Installation

# 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

📋 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

Run DroidMind as a server to connect AI assistants via MCP:

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

Using with AI Assistants

Start DroidMind in SSE mode:
```
droidmind --transport sse
```
Connect your AI assistant using the MCP protocol URI:
```
sse://localhost:6463/sse
```
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
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

With an AI assistant connected to DroidMind, try these 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

DroidMind includes a comprehensive security framework to protect your devices while still allowing AI assistants to be expressive:

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

The security system is designed to be permissive enough to allow common operations while preventing destructive actions. High-risk commands will display warnings to users before execution, and critical operations are blocked entirely without explicit override.

🚧 Development Status

DroidMind is in active development with approximately 90% of planned features implemented. See the Development Roadmap for details on current progress and upcoming features.

Current Focus Areas:

~~UI Automation Development - Adding touch, text input, and intent capabilities~~ ✅ Completed!
~~Security Framework - Adding command validation and safety features~~ ✅ Completed!
~~App Management - Completing app lifecycle and data management tools~~ ✅ Completed!
~~File System Enhancements - Robust file operations and metadata handling~~ ✅ Completed!
Diagnostic Tools - Adding advanced diagnostics ✅ Major progress!
- ~~Screenshot tool~~ ✅ Completed
- ~~Bug report generation~~ ✅ Completed
- ~~Heap dump analysis~~ ✅ Completed
- Screen recording 🔄 Pending
Documentation Enhancement - Comprehensive API docs and tutorials 🔄 In Progress

💻 Development

DroidMind uses UV for dependency management and development workflows. UV is a fast, reliable Python package manager and resolver.

# Update dependencies
uv sync

# Run tests
pytest

# Run linting
ruff check .

# Run type checking
mypy .

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Set up your development environment with UV
Make your changes
Run tests and linting
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the Apache License - see the LICENSE file for details.

Created by Stefanie Jane 🌠

If you find DroidMind useful, buy me a Monster Ultra Violet ⚡️