🤖 DroidMind 🧠

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

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存储库使用uvx运行DroidMind。此方法不需要您手动克隆或安装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设备
• 已安装ADB（Android调试桥接器）并包含在系统PATH中

安装

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

运行DroidMind

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

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

    droidmind --transport stdio
    

  • SSE（用于Web UI或Claude桌面等AI助手）：

    droidmind --transport sse
    

    这通常会在sse://localhost:4256/sse启动一个服务器。
• Docker：请参阅Docker指南以获取在容器中运行DroidMind的命令。

有关在不同环境中运行DroidMind的更多详细信息，请参阅**安装指南**。

🐳 使用Docker运行

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

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

🔮 示例AI助手查询

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

• "列出所有连接的Android设备并显示它们的属性。"
• "对我的Pixel进行截图。"
• "在emulator-5554上安装此APK。"
• "显示来自your_device_serial的最新崩溃日志。"
• "在emulator-5554当前屏幕上点击'Next'按钮。"

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

🔒 安全性

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 '添加一些amazing功能'）。
7. 推送到分支（git push origin feature/amazing-feature）。
8. 打开Pull Request。

📝 许可证

本项目根据Apache许可证授权 - 详细内容请参阅许可证文件。