Skip to content
Back to search

droidmind

Control your Android devices with AI using Model Context Protocol

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hyperb1iss--droidmind/badge.svg)](/listings/hyperb1iss--droidmind)

HTML

<a href="/listings/hyperb1iss--droidmind"><img src="/api/listings/hyperb1iss--droidmind/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Quickstart for IDEs (Zero Install with `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](docs/quickstart.md#1-configure-your-ide-to-run-droidmind-via-uvx)**.

Prerequisites

- 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

Installation

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](docs/installation.md)**.

Running DroidMind

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](docs/quickstart.md). - **Manual Installation**: After installing from source, you can run DroidMind directly. - **Stdio (for direct terminal interaction or some IDE setups):** ```bash droidmind --transport stdio ``` - **SSE (for web UIs or AI assistants like Claude Desktop):** ```bash droidmind --transport sse ``` This usually starts a server at `sse://localhost:4256/sse`. - **Docker**: Refer to the [Docker Guide](docs/docker.md) for commands to run DroidMind in a container.

Refer to the **[Installation Guide](docs/installation.md)** for more details on running DroidMind in different environments.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 166 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # 🤖 DroidMind 🧠
  3. <img src="docs/assets/images/logo_neon_glow_icon.png" alt="DroidMind Logo" width="180" />
  4. [![Python 3.13](https://img.shields.io/badge/python-3.13-9D00FF.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
  5. [![License](https://img.shields.io/badge/license-Apache_2.0-FF00FF.svg?style=for-the-badge&logo=apache&logoColor=white)](LICENSE)
  6. [![Status](https://img.shields.io/badge/status-active_development-39FF14.svg?style=for-the-badge&logo=githubactions&logoColor=white)](docs/plan.md)
  7. [![Code Style](https://img.shields.io/badge/code_style-ruff-00FFFF.svg?style=for-the-badge&logo=ruff&logoColor=white)](https://github.com/astral-sh/ruff)
  8. [![Type Check](https://img.shields.io/badge/type_check-pyright-FFBF00.svg?style=for-the-badge&logo=typescript&logoColor=white)](https://github.com/microsoft/pyright)
  9. [![MCP](https://img.shields.io/badge/protocol-MCP-E6E6FA.svg?style=for-the-badge&logo=anthropic&logoColor=white)](https://modelcontextprotocol.io/)
  10. [![Android](https://img.shields.io/badge/platform-android-A4C639.svg?style=for-the-badge&logo=android&logoColor=white)](https://www.android.com/)
  11. [![Docs](https://img.shields.io/badge/docs-online-FF9E80.svg?style=for-the-badge&logo=gitbook&logoColor=white)](https://hyperb1iss.github.io/droidmind/)
  12. **Control Android devices with AI through the Model Context Protocol**
  13. </div>
  14. 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.
  15. ## 💫 Core Features
  16. DroidMind empowers AI assistants to:
  17. - 📱 **Manage Devices**: Connect via USB/TCP-IP, list devices, view properties, and reboot.
  18. - 📊 **Analyze Systems**: Access logs (logcat, ANR, crash, battery), capture bug reports, and dump heap.
  19. - 📂 **Handle Files**: Browse, read, write, push, pull, delete, and manage device files/directories.
  20. - 📦 **Control Apps**: Install, uninstall, start, stop, clear data, and inspect app details (manifest, permissions, activities).
  21. - 🖼️ **Automate UI**: Perform taps, swipes, text input, and key presses.
  22. - 🐚 **Execute Shell Commands**: Run ADB shell commands with a security-conscious framework.
  23. - 🔒 **Operate Securely**: Benefit from command validation, risk assessment, and sanitization.
  24. - 💬 **Integrate Seamlessly**: Connect with any MCP-compatible client (Claude, Cursor, Cline, etc.).
  25. For a detailed list of capabilities, see the **[User Manual](docs/user_manual/index.md)** and **[MCP Reference](docs/mcp-reference.md)**.
  26. ## 🚀 Getting Started
  27. ### Quickstart for IDEs (Zero Install with `uvx`)
  28. 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**.
  29. Add the following to your IDE's MCP configuration (e.g., `.cursor/mcp.json` for Cursor):
  30. ```json
  31. {
  32. "mcpServers": {
  33. "droidmind": {
  34. "command": "uvx",
  35. "args": [
  36. "--from",
  37. "git+https://github.com/hyperb1iss/droidmind",
  38. "droidmind",
  39. "--transport",
  40. "stdio" // The default and preferred mode for most IDE integrations
  41. ]
  42. }
  43. }
  44. }
  45. ```
  46. Your IDE will be configured to launch DroidMind on demand. Full instructions for this setup are in the **[Quick Start Guide](docs/quickstart.md#1-configure-your-ide-to-run-droidmind-via-uvx)**.
  47. ### Prerequisites
  48. - Python 3.13 (3.14 not yet supported)
  49. - `uv` (Python package manager)
  50. - Android device with USB debugging enabled
  51. - ADB (Android Debug Bridge) installed and in your system's PATH
  52. ### Installation
  53. 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](docs/installation.md)**.
  54. ### Running DroidMind
  55. How you run DroidMind depends on your setup:
  56. - **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](docs/quickstart.md).
  57. - **Manual Installation**: After installing from source, you can run DroidMind directly.
  58. - **Stdio (for direct terminal interaction or some IDE setups):**
  59. ```bash
  60. droidmind --transport stdio
  61. ```
  62. - **SSE (for web UIs or AI assistants like Claude Desktop):**
  63. ```bash
  64. droidmind --transport sse
  65. ```
  66. This usually starts a server at `sse://localhost:4256/sse`.
  67. - **Docker**: Refer to the [Docker Guide](docs/docker.md) for commands to run DroidMind in a container.
  68. Refer to the **[Installation Guide](docs/installation.md)** for more details on running DroidMind in different environments.
  69. ## 🐳 Running with Docker
  70. DroidMind can also be run using Docker for a consistent, containerized environment. This is particularly useful for deployment and isolating dependencies.
  71. 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](docs/docker.md)**.
  72. ## 🔮 Example AI Assistant Queries
  73. With an AI assistant connected to DroidMind, you can make requests like:
  74. - "List all connected Android devices and show their properties."
  75. - "Take a screenshot of my Pixel."
  76. - "Install this APK on `emulator-5554`."
  77. - "Show me the recent crash logs from `your_device_serial`."
  78. - "Tap the 'Next' button on the current screen of `emulator-5554`."
  79. For more inspiration, check out our **[Example Queries and Workflows](docs/user_manual/example_queries.md)** in the User Manual.
  80. ## 🔒 Security
  81. DroidMind incorporates a security framework to protect your devices:
  82. - **Command Validation & Sanitization**
  83. - **Risk Assessment Categorization**
  84. - **Protected Path Operations**
  85. - **Comprehensive Logging**
  86. High-risk operations are flagged, and critical ones are blocked by default. Learn more in our **[Security Considerations](docs/user_manual/security.md)** chapter.
  87. ## 💻 Development
  88. DroidMind uses `uv` for dependency management and development workflows.
  89. ```bash
  90. # Install/update dependencies (creates/updates `.venv`)
  91. uv sync --all-groups
  92. # Run tests
  93. uv run pytest
  94. # Run linting
  95. uv run ruff check .
  96. # Run type checking
  97. uv run pyright
  98. ```
  99. ## 🤝 Contributing
  100. Contributions are welcome! Please feel free to submit a Pull Request.
  101. 1. Fork the repository.
  102. 2. Create your feature branch (`git checkout -b feature/amazing-feature`).
  103. 3. Set up your development environment with `uv`.
  104. 4. Make your changes.
  105. 5. Run tests, linting, and type checking.
  106. 6. Commit your changes (`git commit -m 'Add some amazing feature'`).
  107. 7. Push to the branch (`git push origin feature/amazing-feature`).
  108. 8. Open a Pull Request.
  109. ## 📝 License
  110. This project is licensed under the Apache License - see the [LICENSE](LICENSE) file for details.
  111. ---
  112. <div align="center">
  113. Created by [Stefanie Jane 🌠](https://github.com/hyperb1iss)
  114. If you find DroidMind useful, [buy me a Monster Ultra Violet ⚡️](https://ko-fi.com/hyperb1iss)
  115. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.