The DroidMind server enables AI-assisted control and management of Android devices via ADB through the Model Context Protocol (MCP).
Capabilities include:
Device Management: Connect/disconnect devices, list connected devices, retrieve properties, and reboot
App Control: Install, uninstall, start, stop apps, clear data, and list installed packages
File Operations: Push, pull, list, read, write, delete files/directories and check existence
System Analysis: Access logcat, capture bug reports, and dump process heap
UI Automation: Take screenshots, simulate taps, swipes, text input, and key presses
Shell Commands: Execute ADB shell commands with security validation
Intent Handling: Start app activities with custom intents
Security: Command validation, risk assessment, and sanitization to protect the device
Enables control and interaction with Android devices through ADB, including device management, file system access, app installation, UI automation, system analysis, and debugging features.
Integrates with GitHub for repository management, allowing users to clone the DroidMind repository and contribute through GitHub's pull request workflow.
Integrates with Ko-fi for donations, allowing users to support the project creator by purchasing energy drinks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DroidMind take a screenshot of my device and save it to my computer"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Control Android devices with AI through the Model Context Protocol
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.
DroidMind empowers AI assistants to:
📱 Manage Devices: Connect via USB/TCP-IP, list devices, view properties, and reboot.
📊 Analyze Systems: Access logs (logcat, ANR, crash, battery), capture bug reports, and dump heap.
📂 Handle Files: Browse, read, write, push, pull, delete, and manage device files/directories.
📦 Control Apps: Install, uninstall, start, stop, clear data, and inspect app details (manifest, permissions, activities).
🖼️ Automate UI: Perform taps, swipes, text input, and key presses.
🐚 Execute Shell Commands: Run ADB shell commands with a security-conscious framework.
🔒 Operate Securely: Benefit from command validation, risk assessment, and sanitization.
💬 Integrate Seamlessly: Connect with any MCP-compatible client (Claude, Cursor, Cline, etc.).
For a detailed list of capabilities, see the User Manual and MCP Reference.
Related MCP server: MCP Android Agent
uvx)For the fastest way to integrate DroidMind with an MCP-compatible IDE (like Cursor), you can configure it to run DroidMind directly from its GitHub repository using uvx. This method does not require you to manually clone or install DroidMind first.
Add the following to your IDE's MCP configuration (e.g., .cursor/mcp.json for Cursor):
{
"mcpServers": {
"droidmind": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/hyperb1iss/droidmind",
"droidmind",
"--transport",
"stdio" // The default and preferred mode for most IDE integrations
]
}
}
}Your IDE will be configured to launch DroidMind on demand. Full instructions for this setup are in the Quick Start Guide.
Python 3.13 (3.14 not yet supported)
uv (Python package manager)
Android device with USB debugging enabled
ADB (Android Debug Bridge) installed and in your system's PATH
For detailed instructions on setting up DroidMind, including the quick IDE integration with uvx (covered in the Quick Start), manual installation from source, or using Docker, please see our comprehensive Installation Guide.
How you run DroidMind depends on your setup:
IDE Integration (via uvx): Your IDE automatically manages running DroidMind as configured in its MCP settings (e.g., mcp.json). See the Quick Start Guide.
Manual Installation: After installing from source, you can run DroidMind directly.
Stdio (for direct terminal interaction or some IDE setups):
droidmind --transport stdioSSE (for web UIs or AI assistants like Claude Desktop):
droidmind --transport sseThis usually starts a server at sse://localhost:4256/sse.
Docker: Refer to the Docker Guide for commands to run DroidMind in a container.
Refer to the Installation Guide for more details on running DroidMind in different environments.
DroidMind can also be run using Docker for a consistent, containerized environment. This is particularly useful for deployment and isolating dependencies.
For comprehensive instructions on building the Docker image and running DroidMind in a container with stdio or SSE transport, including notes on ADB device access, please refer to our Docker Guide.
With an AI assistant connected to DroidMind, you can make requests like:
"List all connected Android devices and show their properties."
"Take a screenshot of my Pixel."
"Install this APK on emulator-5554."
"Show me the recent crash logs from your_device_serial."
"Tap the 'Next' button on the current screen of emulator-5554."
For more inspiration, check out our Example Queries and Workflows in the User Manual.
DroidMind incorporates a security framework to protect your devices:
Command Validation & Sanitization
Risk Assessment Categorization
Protected Path Operations
Comprehensive Logging
High-risk operations are flagged, and critical ones are blocked by default. Learn more in our Security Considerations chapter.
DroidMind uses uv for dependency management and development workflows.
# Install/update dependencies (creates/updates `.venv`)
uv sync --all-groups
# Run tests
uv run pytest
# Run linting
uv run ruff check .
# Run type checking
uv run pyrightContributions 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, linting, and type checking.
Commit your changes (git commit -m 'Add some amazing feature').
Push to the branch (git push origin feature/amazing-feature).
Open a Pull Request.
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 ⚡️
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:
action="install_app"
Requires: apk_path
Optional: reinstall, grant_permissions
action="uninstall_app"
Requires: package
Optional: keep_data
action="start_app"
Requires: package
Optional: activity
3b. action="start_intent"
Requires: package, activity
Optional: extras
action="stop_app"
Requires: package
action="clear_app_data"
Requires: package
action="list_packages"
Optional: include_system_apps, include_app_name, include_apk_path, max_packages
action="get_app_manifest"
Requires: package
action="get_app_permissions"
Requires: package
action="get_app_activities"
Requires: package
action="get_app_info"
Requires: package
Inputs: serial (required), action (required), package, apk_path, +9 more. Returns: result
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:
action="list_devices"
No specific arguments required beyond ctx.
action="connect_device"
Requires: ip_address
Optional: port
action="disconnect_device"
Requires: serial
action="reboot_device"
Requires: serial
Optional: mode (e.g., "normal", "recovery", "bootloader")
action="device_properties"
Requires: serial
Inputs: action (required), serial, ip_address, port, +1 more. Returns: result
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
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:
action="list_directory": Lists contents of a directory.
Requires: path (directory path on device).
Returns: Formatted string of directory contents.
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.
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.
action="delete_file": Deletes a file or directory from the device.
Requires: path (path to delete on device).
Returns: String message confirming deletion.
action="create_directory": Creates a directory on the device.
Requires: path (directory path to create on device).
Returns: String message confirming creation.
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.
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.
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.
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
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:
action="get_device_logcat"
Optional: lines, filter_expr, buffer, format_type, max_size.
action="get_app_logs"
Requires: package.
Optional: lines.
action="get_anr_logs"
No specific arguments beyond serial and ctx.
action="get_crash_logs"
No specific arguments beyond serial and ctx.
action="get_battery_stats"
No specific arguments beyond serial and ctx.
Inputs: serial (required), action (required), package, lines, +4 more. Returns: result
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.
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
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
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
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.
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.
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.
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.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Melaya is a remote MCP server. It gives an assistant hands on your own Android phone and browser: it reads the screen through the accessibility tree, then taps, types and navigates inside the apps and sites you allow-list, with no per-app API. It also builds, schedules and runs agent pipelines across 6k+ connected tools. OAuth 2.1, nothing to install.
MCP server for building and testing AI agents with multi-model experimentation and insights.
