droidmind

DroidMind is an MCP (Model Context Protocol) server that exposes Android Debug Bridge (ADB) functionalities as tools and resources. It allows AI assistants (such as Claude, Cursor, and other MCP-compatible clients) to interact directly with Android devices using natural language.

Key capabilities include:

• Direct Device Control: Executing commands, managing files, and automating UI interactions.
• Analysis and Diagnosis: Retrieving logs, inspecting device properties, and capturing diagnostic information.
• Workflow Integration: Seamlessly integrating device interactions into AI-driven development loops.

DroidMind provides an AI assistant with the following capabilities via the Model Context Protocol (MCP):

• Device Management: Connect via USB/TCP-IP, list devices, view properties, and reboot.
• System Analysis: Access logs (logcat, ANR, crash, battery), capture bug reports, and dump heap.
• File Management: Browse, read, write, push, pull, delete, and manage device files/directories.
• App Control: Install, uninstall, start, stop, clear data, and inspect app details (manifest, permissions, activities).
• UI Automation: Perform taps, swipes, text input, and key presses.
• Shell Execution: Run ADB shell commands within a security-conscious framework.
• Security: Built-in command validation, risk assessment, and sanitization.

The serial number is the unique identifier used to target specific devices when multiple connections are present. DroidMind uses these strings to distinguish between different hardware or instances.

Serial Formats:

• Physical USB Devices: A unique alphanumeric string (e.g., 1A2B3C4D5E6F or R5CR707QL9X).
• Emulators: Typically follow the pattern emulator-XXXX (e.g., emulator-5554).
• Networked Devices (TCP/IP): Formatted as ip_address:port (e.g., 192.168.1.123:5555).

You must provide the correct serial when the AI assistant prompts for a device or when initiating specific commands.

DroidMind applies specific restrictions based on file paths and device permissions:

Protected Paths

Operations targeting critical system paths are heavily scrutinized:

• Paths: /system, /vendor, /product, /proc, /dev, etc.
• Read-only operations (e.g., ls, cat) on these paths are permitted but flagged as MEDIUM or HIGH risk.
• Write operations or modifications to these paths are generally disallowed or flagged as CRITICAL risk and blocked.

Principle of Least Privilege

DroidMind's capabilities are limited by the permissions of the ADB daemon on the device:

• Non-Rooted Devices: DroidMind cannot perform operations requiring root privileges.
• Rooted Devices: If ADB is configured to run as root, DroidMind inherits these elevated privileges. Use extreme caution in this configuration as the impact of any command is significantly increased.

To prevent overwhelming the AI or terminal, DroidMind enforces limits on command output. If a command exceeds these limits, DroidMind appends a truncation note to the end of the output.

Limits

• max_lines: Controls line count. Default is 1000. Use positive values for the start of output and negative values for the end.
• max_size: Controls total character count. Default is 100,000 characters.

Truncation Indicators

When output is cut off, you will see messages such as:

• [Output truncated: 100000 chars, 1500 lines]
• [Command output truncated: 1500 lines, 97.7 KB]

You can integrate DroidMind with MCP-compatible IDEs (like Cursor) without manually cloning or installing the repository by using uvx. This method allows the IDE to launch DroidMind directly from its GitHub repository.

To set this up, add the following configuration to your IDE's MCP settings (for example, .cursor/mcp.json in Cursor):

{
  "mcpServers": {
    "droidmind": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hyperb1iss/droidmind",
        "droidmind",
        "--transport",
        "stdio"
      ]
    }
  }
}

Note: stdio is the default and preferred transport mode for most IDE integrations.

Before setting up DroidMind, ensure your environment meets the following requirements:

• Python & UV: Python 3.13 must be installed. Note that Python 3.14 is not yet supported. The uv package manager is required as DroidMind uses uvx for zero-install integration.
• AI Assistant with MCP Support: An AI client that supports the Model Context Protocol (MCP), such as Claude Desktop or Cursor.
• Android Device/Emulator: A physical Android device connected via USB (with USB debugging enabled) or an active emulator. For network connections, ADB over TCP/IP must be configured.
• ADB: The Android Debug Bridge (ADB) must be installed and available in your system's PATH.

Connecting USB devices directly to a Docker container is complex. The recommended approach is to use ADB over TCP/IP on your Android device. This allows the container to connect to the device over your local network.

Setup Steps:

1. Enable ADB over TCP/IP on the device:
   • Connect device via USB to host.
   • Find device IP (e.g., 192.168.1.50).
   • Run adb tcpip 5555 from your host.
   • Disconnect USB.
   • Run adb connect <device_ip_address>:5555 from your host to verify.
2. Connect via DroidMind:
   • Once DroidMind is running in the container, use its connect_device tool via your AI assistant to connect to <device_ip_address>:5555.

DroidMind is a server and does not prompt for user confirmation directly. Instead, it relies on the AI assistant (the MCP client) to implement a confirmation workflow based on DroidMind's risk assessments.

Recommended Workflow for AI Assistants:

1. DroidMind flags a tool call as HIGH or CRITICAL risk.
2. The AI assistant intercepts this risk assessment.
3. The AI assistant presents the risk to the user and asks for explicit approval (e.g., Are you sure you want to proceed? (yes/no)).
4. The AI assistant only proceeds with the instruction if the user provides confirmation.