Droid MCP

DroidMCP

MCP（模型上下文协议）服务器，使AI代理能够完全控制Android设备。DroidMCP通过stdio传输公开了34个工具，允许任何兼容MCP的客户端（Claude Code、Claude Desktop、自定义代理）通过ADB、可访问性服务和低级适配器与物理设备和模拟器进行交互。

基于设备交互层构建 DroidBot，将重依赖项（~2GB的torch、numpy等）剥离为单个依赖项： mcp[cli].

特性

• 语义UI描述 --将Android视图层次结构转换为具有连续元素ID的类似HTML的标记，以便AI代理可以理解任何屏幕并与之交互
• 34工具 涵盖设备连接、应用程序管理、UI检查、输入操作、文件操作、可观察性和仿真器控制
• 快速截图 通过带有ADB screencap回退功能的minicap（真实设备）
• 文本输入 通过自定义DroidBot输入法进行可靠的Unicode文本输入
• 流程和日志监控 配备内存缓冲区，实现实时可观察性
• 模拟器附加功能 --通过telnet控制台模拟通话、短信、GPS和手势
• 零重依赖 --只需要 mcp[cli] （在您的路径上加上ADB）

先决条件

• Python 3.10+
• 安卓调试桥 已安装并位于PATH中(Android SDK平台工具)
• Android设备或模拟器 通过连接和可见 adb devices
• 对于物理设备：在“开发人员选项”中启用USB调试
• 对于模拟器：任何标准的Android模拟器（Android Studio AVD、Genymotion等）

安装

# Clone the repo
git clone https://github.com/nicehash/DroidMCP.git
cd DroidMCP

# Create a virtual environment and install
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e .

配置

克劳德代码

添加 ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "droidmcp": {
      "command": "/absolute/path/to/DroidMCP/.venv/bin/python",
      "args": ["-m", "droidmcp"]
    }
  }
}

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "droidmcp": {
      "command": "/absolute/path/to/DroidMCP/.venv/bin/python",
      "args": ["-m", "droidmcp"]
    }
  }
}

其他MCP客户端

DroidMCP使用stdio传输。从以下内容开始：

python -m droidmcp

或使用已安装的入口点：

droidmcp

工具参考

设备连接

设备信息

应用程序管理

UI状态捕获

get_ui_description 是 AI代理的核心工具。它返回如下标记：

Settings
Type here

Welcome to the app

go back

这 id 值由以下人员使用 tap_element, set_text，以及 scroll 针对特定元素。

输入操作

文件操作

可观测性

模拟器特定

这些工具需要一个具有telnet控制台访问权限的模拟器设备。

效用

典型使用流程

以下是AI代理通常如何使用DroidMCP：

1. list_devices          -> see what's connected
2. connect_device        -> initialize (takes ~10s)
3. get_ui_description    -> understand the current screen
4. tap_element(id=3)     -> interact with an element
5. get_ui_description    -> see the result
6. set_text("hello", element_id=1)  -> type into an input field
7. press_key("BACK")     -> navigate back
8. take_screenshot       -> visual confirmation
9. disconnect_device     -> clean up

错误处理

所有工具归还 {"status": "ok", ...} 关于成功。失败时，工具会引发键入错误：

建筑

src/droidmcp/
├── server.py            # FastMCP server with all 34 tool definitions
├── device_manager.py    # Global device singleton, error types, require_device decorator
├── device.py            # Device class managing all adapters
├── device_state.py      # UI state representation with semantic HTML generation
├── intent.py            # Android intent builder
├── utils.py             # Helpers (get_available_devices, md5)
├── adapter/
│   ├── adapter.py       # Base adapter class
│   ├── adb.py           # ADB interface (touch, shell, display info, etc.)
│   ├── droidbot_app.py  # Accessibility service connection for view hierarchy
│   ├── droidbot_ime.py  # Custom IME for reliable text input
│   ├── minicap.py       # Fast screenshot capture via minicap binary
│   ├── logcat.py        # Real-time log capture with in-memory buffer
│   ├── process_monitor.py # Process table monitoring
│   └── telnet.py        # Emulator telnet console (calls, SMS, GPS)
└── resources/
    ├── droidbotApp.apk  # Accessibility service APK (auto-installed on connect)
    └── minicap/          # minicap binaries for various ABIs/SDK levels

关键设计决策：

• 全局设备单例：工具调用之间的连接持续存在。适配器初始化（安装APK、启动服务）只发生一次 connect_device.
• 缓存的UI状态: get_ui_description 缓存状态 tap_element/set_text 可以解析元素ID而无需重新获取。
• 复制自DroidBot：适配器层改编自DroidBot，删除了大量依赖项（networkx、treelib、numpy、PIL、torch、androguard）。所有功能都使用Python stdlib。

致谢

设备交互层改编自 DroidBot DroidMCP提取并更新了核心适配器代码，以用作独立的MCP服务器。

许可证

看 许可证 了解详情。