Android ADB Server

一个通过 ADB（Android Debug Bridge）提供 Android 设备编程控制的 MCP（Model Context Protocol）服务器。该服务器暴露多种 Android 设备管理能力，可被 MCP 客户端访问，例如 Claude Desktop 和代码编辑器（如 Cursor、Kiro）。

功能特性

• 🔧 ADB 命令执行
• 📸 设备屏幕截图
• 🔍 截图 OCR 文字识别
• 🎯 UI 布局分析
• 📱 设备应用包管理
• 👆 触摸操作（点击、滑动、长按、文本输入、按键）
• 🚀 应用管理（启动、停止、安装、卸载）
• 📂 文件传输（推送、拉取）
• 🔋 设备信息与电池状态
• 📹 屏幕录制
• 📋 日志获取
• 📶 WiFi 开关控制
• ⏳ 元素等待

前置要求

• Python 3.11+
• ADB（Android Debug Bridge）已安装并配置
• Android 设备或模拟器（模拟器未经测试）
• Tesseract OCR 引擎（用于文字识别功能）

安装

方式一：通过 pip 安装（推荐）

pip install android-adb

方式二：通过 uvx 直接运行（无需安装）

uvx android-adb

方式三：从源码安装

git clone https://github.com/xuegao-tzx/android-adb-mcp.git
cd android-adb-mcp
uv pip install -e "."

安装 Tesseract OCR 引擎

# Ubuntu/Debian
sudo apt install tesseract-ocr

# macOS (使用 Homebrew)
brew install tesseract

# Windows
# 从以下地址下载安装程序: https://github.com/UB-Mannheim/tesseract/wiki

配置

服务器支持灵活的设备配置，适用于多种使用场景。

配置文件查找顺序

服务器会按以下顺序查找 config.yaml：

1. 当前工作目录下的 config.yaml
2. ~/.android-adb/config.yaml（用户 home 目录）

如果未找到配置文件，服务器会在仅连接一个设备时自动选择。

设备选择模式

1. 自动选择（单设备推荐）

• 无需配置文件
• 自动连接唯一已连接的设备

2. 手动指定设备

创建 config.yaml：

device:
  name: "your-device-serial-here"  # 来自 'adb devices' 的设备标识符

查找设备序列号

adb devices

输出示例：

List of devices attached
13b22d7f        device
emulator-5554   device

使用第一列的值作为设备名称。

使用场景

场景	是否需要配置	行为
单设备连接	不需要	✅ 自动连接该设备
多设备，指定某一个	需要 config.yaml	✅ 连接到指定设备
多设备，无配置	不需要	❌ 显示错误并列出可用设备
无设备连接	不适用	❌ 显示"无设备"错误

使用方法

需要 MCP 客户端来使用此服务器。

Claude Desktop

在 Claude Desktop 配置文件中添加：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

pip 安装方式：

{
  "mcpServers": {
    "android": {
      "command": "android-adb"
    }
  }
}

uvx 方式（无需预安装）：

{
  "mcpServers": {
    "android": {
      "command": "uvx",
      "args": ["android-adb"]
    }
  }
}

Kiro / Cursor 等编辑器

在项目的 MCP 配置文件中添加：

{
  "mcpServers": {
    "android": {
      "command": "uvx",
      "args": ["android-adb"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

可用工具

服务器暴露以下 41 个工具：

基础工具

工具	说明
list_devices()	列出所有已连接的 Android 设备及其状态
get_packages()	获取设备上所有已安装的应用包名
execute_adb_shell_command(command)	执行 ADB shell 命令并返回输出
get_uilayout()	获取当前界面中可点击元素的信息
get_screenshot()	截取设备屏幕截图并返回
get_screenshot_ocr(search_string, confidence_threshold)	在截图中搜索指定文本并返回位置坐标
get_screenshot_text(confidence_threshold)	使用 OCR 获取截图中的所有文本及坐标
get_package_action_intents(package_name)	获取指定包的所有非数据 Action

触摸与输入操作

工具	说明
tap(x, y)	点击屏幕指定坐标
double_tap(x, y, interval)	双击屏幕指定坐标
long_press(x, y, duration)	长按屏幕指定坐标
swipe(x1, y1, x2, y2, duration)	从一个坐标滑动到另一个坐标
pinch_zoom(cx, cy, scale, duration)	在指定中心点执行缩放手势
input_text(text)	在当前焦点输入框中输入文本
press_key(keycode)	发送按键事件（HOME/BACK/ENTER 等）

应用管理

工具	说明
launch_app(package_name)	启动指定应用
start_activity(package_name, activity_name, extras)	启动指定 Activity
stop_app(package_name)	强制停止指定应用
clear_app_data(package_name)	清除指定应用的所有数据
install_apk(apk_path)	安装 APK 到设备
uninstall_app(package_name)	卸载指定应用
get_current_activity()	获取当前前台 Activity 的包名和类名
open_url(url)	在设备上打开指定 URL
grant_permission(package_name, permission)	授予应用运行时权限
revoke_permission(package_name, permission)	撤销应用运行时权限

设备信息与文件管理

工具	说明
get_device_info()	获取设备基础信息（型号、系统版本、分辨率等）
get_battery_info()	获取电池信息（电量、充电状态、温度等）
push_file(local_path, remote_path)	推送本地文件到设备
pull_file(remote_path, local_path)	从设备拉取文件到本地
list_files(remote_path)	列出设备上指定目录的文件和文件夹

设备设置

工具	说明
set_wifi(enable)	开启或关闭 WiFi
set_bluetooth(enable)	开启或关闭蓝牙
toggle_airplane_mode()	切换飞行模式
set_screen_brightness(level)	设置屏幕亮度（0-255）
set_screen_orientation(orientation)	设置屏幕方向（auto/portrait/landscape 等）

剪贴板

工具	说明
get_clipboard()	获取设备剪贴板内容
set_clipboard(text)	设置设备剪贴板内容

进阶能力

工具	说明
record_screen(duration)	录制设备屏幕，最大 180 秒
get_logcat(filter_expr, lines)	获取设备日志
clear_logcat()	清除日志缓冲区
wait_for_element(text, timeout)	等待指定文本的元素出现在界面上

贡献

欢迎贡献代码！

致谢

• 基于 Model Context Protocol (MCP) 构建