<div align="center">

🤖 DroidMind 🧠

<img src="docs/assets/images/logo_neon_glow_icon.png" alt="DroidMind Logo" width="180" />

通过模型上下文协议（MCP）使用AI控制Android设备

</div>

DroidMind 是一个强大的桥梁，连接AI助手与Android设备，通过自然语言实现控制、调试和系统分析。通过实现模型上下文协议（MCP），DroidMind 允许AI模型通过ADB以安全、结构化的方式直接与Android设备交互。作为代理编码工作流程的一部分时，DroidMind 可以使您的助手直接参与到设备的构建和调试中。

💫 核心功能

DroidMind 赋予AI助手以下能力：

• 📱 管理设备：通过USB/TCP-IP连接，列出设备，查看属性，重启设备。
• 📊 分析系统：访问日志（logcat、ANR、崩溃、电池），捕获错误报告，转储堆。
• 📂 处理文件：浏览、读取、写入、推送、拉取、删除和管理设备文件/目录。
• 📦 控制应用：安装、卸载、启动、停止、清除数据，检查应用详情（清单、权限、活动）。
• 🖼️ 自动化UI：执行点击、滑动、文本输入和按键操作。
• 🐚 执行Shell命令：在安全框架下运行ADB shell命令。
• 🔒 安全操作：受益于命令验证、风险评估和清理。
• 💬 无缝集成：连接到任何兼容MCP的客户端（如Claude、Cursor、Cline等）。

详细的功能列表，请参阅**用户手册和MCP参考**。

🚀 快速开始

集成IDE（零安装，使用uvx）

为了最快地将DroidMind集成到兼容MCP的IDE（如Cursor）中，您可以配置它直接从GitHub仓库运行DroidMind，使用uvx。这种方法不需要您手动克隆或安装DroidMind。

在IDE的MCP配置中添加以下内容（例如，对于Cursor是.cursor/mcp.json）：

{
  "mcpServers": {
    "droidmind": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hyperb1iss/droidmind",
        "droidmind",
        "--transport",
        "stdio" // 大多数IDE集成的默认和首选模式
      ]
    }
  }
}

您的IDE将被配置为按需启动DroidMind。完整的设置说明请参阅**快速开始指南**。

前提条件

• Python 3.13 或更高版本
• uv（Python包管理器）
• 启用USB调试的Android设备
• 安装并添加到系统PATH中的ADB（Android调试桥）

安装

详细的DroidMind设置说明，包括快速IDE集成（使用uvx）、从源代码手动安装或使用Docker，请参阅我们的综合**安装指南**。

运行DroidMind

如何运行DroidMind取决于您的设置：

• IDE集成（通过uvx）：IDE会根据其MCP设置（例如mcp.json）自动管理DroidMind的运行。请参阅快速开始指南。
• 手动安装：从源代码安装后，可以直接运行DroidMind。
  • Stdio（用于直接终端交互或某些IDE设置）：

    droidmind --transport stdio
    

  • SSE（用于Web UI或AI助手如Claude Desktop）：

    droidmind --transport sse
    

    这通常会在sse://localhost:4256/sse启动一个服务器。
• Docker：请参阅Docker指南，了解如何在容器中使用stdio或SSE传输运行DroidMind的命令。

更多关于不同环境中运行DroidMind的细节，请参阅**安装指南**。

🐳 使用Docker运行

DroidMind也可以使用Docker运行，以获得一致的容器化环境。这对于部署和隔离依赖项特别有用。

有关构建Docker镜像和使用stdio或SSE传输在容器中运行DroidMind的详细说明，包括ADB设备访问注意事项，请参阅我们的**Docker指南**。

🔮 示例AI助手查询

连接到DroidMind的AI助手可以进行如下请求：

• “列出所有已连接的Android设备，并显示它们的属性。”
• “为我的Pixel拍摄一张屏幕截图。”
• “在emulator-5554上安装这个APK。”
• “显示来自your_device_serial的最近崩溃日志。”
• “点击emulator-5554当前屏幕上的‘下一步’按钮。”

更多灵感，请查阅用户手册中的**示例查询和工作流**。

🔒 安全性

DroidMind集成了一个安全框架来保护您的设备：

• 命令验证与清理
• 风险评估分类
• 受保护路径操作
• 全面的日志记录

高风险操作会被标记，默认情况下关键操作会被阻止。了解更多，请参阅我们的**安全考虑**章节。

💻 开发

DroidMind使用uv进行依赖管理和开发工作流程。

# 安装/更新依赖（克隆后激活.venv）
uv pip install -e .[dev,sse]

# 运行测试
pytest

# 运行代码检查
ruff check .

# 运行类型检查
pyright # 确保已安装pyright或使用ruff的类型检查功能

🤝 贡献

欢迎贡献！请随时提交Pull Request。

1. 分叉仓库。
2. 创建您的功能分支（git checkout -b feature/amazing-feature）。
3. 使用uv设置您的开发环境。
4. 进行更改。
5. 运行测试、代码检查和类型检查。
6. 提交更改（git commit -m '添加一些惊人的功能'）。
7. 推送到分支（git push origin feature/amazing-feature）。
8. 打开Pull Request。

📝 许可证

本项目采用Apache许可证——详情请参见LICENSE文件。

---

<div align="center">

由 Stefanie Jane 🌠 创作

如果您觉得DroidMind有用，请给我买一杯Monster Ultra Violet ⚡️

</div>