使用说明

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

工具参考

设备连接

工具	参数	说明
`list_devices`	--	列出ADB可见的所有Android设备
`connect_device`	`device_serial?`, `is_emulator?`, `grant_perm?`	连接到设备并初始化所有适配器。需要5到15秒。如果省略串行，则使用第一个可用设备
`disconnect_device`	--	断开并清理所有适配器

设备信息

工具	参数	说明
`get_device_info`	--	获取设备序列号、型号、SDK版本、发布版本和显示信息

应用程序管理

工具	参数	说明
`install_app`	`apk_path`, `grant_perm?`	在设备上安装APK
`uninstall_app`	`package_name`	按程序包名称卸载应用程序
`start_app`	`package_name`	启动应用程序
`stop_app`	`package_name`	强制停止应用程序
`is_app_foreground`	`package_name`	检查应用程序是否在前台
`list_installed_apps`	--	列出所有已安装的软件包

UI状态捕获

工具	参数	说明
`take_screenshot`	--	以base64编码的JPEG/PNG格式捕获屏幕
`get_ui_description`	--	使用元素ID获取当前屏幕的语义HTML
`get_ui_hierarchy`	--	获取原始视图层次结构、活动堆栈和服务
`get_current_activity`	--	获取当前前台活动名称
`get_activity_stack`	--	获取完整的活动返回堆栈

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

<button id=0 text='Settings'>Settings</button>
<input id=1 text='Search'>Type here</input>
<checkbox id=2 checked=False text='Remember me'></checkbox>
<p id=3>Welcome to the app</p>
<button id=4>go back</button>

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

输入操作

工具	参数	说明
`tap`	`x`, `y`	点击屏幕绝对坐标
`tap_element`	`element_id`	按ID点击元素 `get_ui_description`
`long_tap`	`x`, `y`, `duration?`	在坐标处长按（默认2000ms）
`swipe`	`start_x`, `start_y`, `end_x`, `end_y`, `duration?`	在两点之间滑动
`scroll`	`direction`, `element_id?`	向上/向下/向左/向右滚动，可选地在元素内滚动
`set_text`	`text`, `element_id?`	键入文本；可选择先点击元素以将其聚焦
`press_key`	`key`	按“返回”、“主页”、“菜单”、“输入”、“电源”、“音量_打开”、“体积_关闭”
`send_intent`	`action?`, `data_uri?`, `component?`, `prefix?`, `extras?`	通过活动管理器发送Android意图

文件操作

工具	参数	说明
`push_file`	`local_path`, `remote_path?`	将文件推送到设备（默认：/sdcard/）
`pull_file`	`remote_path`, `local_path`	从设备中提取文件

可观测性

工具	参数	说明
`get_running_services`	--	列出正在运行的Android服务
`get_logcat`	`lines?`, `filter_tag?`	使用可选标记过滤器获取最近的logcat输出
`get_processes`	--	列出正在运行的进程（pid、ppid、user、name）

模拟器特定

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

工具	参数	说明
`emulator_call`	`phone_number`, `action`	模拟电话（接听/取消/接听）
`emulator_sms`	`phone_number`, `content`, `action`	模拟短信（发送/接收）
`emulator_set_gps`	`longitude`, `latitude`	设置GPS坐标
`emulator_shake`	--	模拟摇动手势

效用

工具	参数	说明
`shell_command`	`command`	运行任意ADB shell命令
`get_app_pid`	`package_name`	获取正在运行的应用程序的PID

典型使用流程

以下是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", ...} 关于成功。失败时，工具会引发键入错误：

错误	何时
`DeviceNotConnected`	之前调用的任何工具 `connect_device`
`DeviceConnectionFailed`	无法访问ADB或适配器安装失败
`ElementNotFound`	`element_id` 超出范围 `tap_element`/`set_text`/`scroll`
`StaleState`	无需事先调用基于元素的工具 `get_ui_description`
`AdapterUnavailable`	物理设备上使用的仿真器工具
`ADBCommandFailed`	基础ADB命令返回错误
`InvalidParameter`	方向、动作无效或缺少必需的参数

建筑

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服务器。

许可证

看许可证了解详情。