Skip to main content
Glama
Sign In
ADB MCP Server

ADB MCP Server

by LLL-404
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

English · 简体中文

ADB MCP Server

通过 MCP 协议控制 Android 设备

20 个工具 · MCP 标准协议 · Node ≥ 18 · MIT

IMPORTANT

为 AI 助手（如 Claude）提供完整的 ADB 操作能力：设备信息、屏幕、输入、应用、Shell、文件、UI 解析，七大类一应俱全。

功能特性

  • 设备信息 — 获取型号、Android 版本、屏幕分辨率、电池状态、IP、序列号

  • 屏幕控制 — 截图、获取屏幕尺寸

  • 输入模拟 — 点击、滑动、输入文本、按键事件（HOME/BACK/音量等）

  • 应用管理 — 列出/查看/启动/停止应用、获取前台应用

  • Shell 执行 — 执行任意 ADB Shell 命令、Termux 命令（需确认）

  • 文件传输 — 从设备拉取文件到本地

  • UI 解析 — 获取界面元素树、按文本定位并点击

Related MCP server: scrcpy-mcp

⌨️ 快速开始

# 1. 安装依赖
npm install

# 2. 构建
npm run build

# 3. 配置 MCP
# 将 opencode.json 中的 mcpServers.adb 配置添加到你的 MCP 客户端

# 4. 运行
npm start

日常手感：npm install → npm run build → npm start

⚙️ 配置

在 MCP 客户端中添加以下配置（以 opencode 为例）：

{
  "mcpServers": {
    "adb": {
      "command": "node",
      "args": ["path/to/adb-mcp-server/dist/index.js"],
      "env": {
        "ADB_PATH": "C:\\Users\\<username>\\AppData\\Local\\Android\\platform-tools\\adb.exe",
        "ADB_SCREENSHOT_DIR": "path/to/screenshots"
      }
    }
  }
}

环境变量

变量

说明

默认值

ADB_PATH

adb 可执行文件的完整路径（不设置则自动查找 PATH 和常用路径）

自动检测

ADB_SCREENSHOT_DIR

截图文件保存目录

screenshots/

🧰 工具列表

设备信息

工具

描述

adb_device_info

获取设备信息：型号、Android 版本、屏幕、电池、IP、序列号

adb_battery

获取电池电量、充电状态、温度、健康度

adb_clipboard

读取剪贴板内容（Android 10+）

屏幕

工具

描述

adb_screenshot

截图，支持返回文件路径或 base64

adb_screen_size

获取屏幕分辨率

输入

工具

描述

adb_tap

在指定坐标点击

adb_swipe

从 (x1,y1) 滑动到 (x2,y2)，支持设置持续时间

adb_text

输入文本（自动选择 ASCII 直输或 Unicode 剪贴板方案）

adb_keyevent

发送按键事件（HOME、BACK、ENTER、音量等 60+ 按键）

应用管理

工具

描述

adb_list_packages

列出已安装应用，支持按关键字、类型（用户/系统/全部）筛选

adb_app_info

获取应用详情：版本、SDK 目标、安装时间、权限列表

adb_app_launch

启动应用，可指定 Activity

adb_app_stop

强制停止应用

adb_current_app

获取当前前台应用包名和 Activity

Shell

工具

描述

需确认

adb_shell

执行 Android Shell 命令

✅ confirm=true

adb_termux_exec

在 Termux bash 中执行命令

✅ confirm=true

文件

工具

描述

adb_pull

从设备拉取文件到本地

UI

工具

描述

adb_ui_tree

获取界面无障碍元素树（含位置、可点击状态等）

adb_observe

截图 + UI 树一站式观察屏幕

adb_tap_text

按文本查找 UI 元素并点击

使用示例

查看设备信息：

调用 adb_device_info 即可获取设备型号、Android 版本、屏幕参数、电池状态等。

输出示例：
- Model: Google Pixel 7
- Android: 14 (SDK 34)
- Screen: 1080x2400
- Battery: 85% (charging, 32.5°C)

观察屏幕并点击：

1. 调用 adb_observe 获取当前屏幕截图（base64）+ UI 元素列表
2. AI 根据 UI 元素坐标，调用 adb_tap 或 adb_tap_text 进行操作

截图：

调用 adb_screenshot，截图自动保存到 ADB_SCREENSHOT_DIR

🧱 环境依赖

运行时

依赖

版本

说明

Node.js

>= 18

JavaScript 运行环境

@modelcontextprotocol/sdk

^1.6.1

MCP 协议服务端 SDK

zod

^3.23.8

输入参数模式校验

开发

依赖

版本

说明

typescript

^5.7.2

TypeScript 编译器

tsx

^4.19.2

TypeScript 开发热重载

@types/node

^22.10.0

Node.js 类型定义

系统

需求

说明

ADB

Android Debug Bridge，详见安装 ADB

Android 设备

通过 USB 连接，开启开发者选项和 USB 调试；或使用 Android 模拟器

Termux（可选）

用于 adb_termux_exec 工具，需在设备上安装 Termux

安装 ADB

Windows 用户可直接运行项目根目录的 setup-adb.ps1 脚本一键安装：

.\setup-adb.ps1

该脚本会依次尝试 winget 安装和手动下载安装。

其他方式：

  • Android Developer 官网 下载 Platform Tools

  • macOS: brew install android-platform-tools

  • Linux: apt install adb 或 pacman -S android-tools

🗂 仓库地图

src/
  ├── index.ts          服务器入口
  ├── services/
  │   ├── adb.ts        ADB 命令执行核心
  │   └── ui-parser.ts  界面元素树解析
  └── tools/
      ├── device.ts     设备信息
      ├── screen.ts     截图与屏幕
      ├── input.ts      输入模拟
      ├── app.ts        应用管理
      ├── shell.ts      Shell 执行
      ├── file.ts       文件传输
      └── ui.ts         UI 观察

🔒 安全说明

WARNING

Shell 需确认 —— adb_shell 和 adb_termux_exec 必须显式设置 confirm=true 才能执行，防止误操作。

按键白名单 —— 按键事件走白名单机制，仅允许安全的系统按键（无电源键、重启等危险按键）。

长度限制 —— 文本输入限制 500 字符。

许可证

MIT

🌍 个人站 · GitHub · 📧 邮箱

Available Tools

20 tools
adb_app_infoGet App InfoA
Read-onlyIdempotent

Get version, SDK, install date, permissions for an installed app.

Inputs: package_name (required), response_format.

adb_app_launchLaunch AppA

Launch an app by package name. Optionally specify an activity.

Inputs: package_name (required), activity.

adb_app_stopStop AppA

Force-stop an app by package name.

Inputs: package_name (required).

adb_batteryGet Battery StatusA
Read-onlyIdempotent

Get battery level, charging status, and temperature.

Inputs: response_format.

adb_clipboardGet Device Clipboard ContentA
Read-onlyIdempotent

Get clipboard text (Android 10+).

Inputs: no named parameters.

adb_current_appGet Current Foreground AppA
Read-onlyIdempotent

Get the package name and activity of the foreground app.

Inputs: no named parameters.

adb_device_infoGet Android Device InfoB
Read-onlyIdempotent

Get device model, Android version, screen, battery, IP, and serial.

Inputs: response_format.

adb_keyeventSend Key EventA

Send a safe key event (HOME, BACK, ENTER, etc.). Allowed: navigation, editing, media, alphanumeric keys.

Inputs: key (required).

adb_list_packagesList Installed PackagesA
Read-onlyIdempotent

List installed packages, filterable by keyword and type (user/system/all).

Inputs: filter, type, limit, response_format.

adb_observeObserve Screen (Screenshot + UI Tree)A
Read-only

Take screenshot (base64) + UI tree in one call. Recommended for "looking" at the screen.

Inputs: max_elements.

adb_pullPull File from DeviceA
Read-only

Copy a file from device to local computer.

Inputs: remote_path (required), local_dir.

adb_screenshotTake ScreenshotA
Read-only

Take screenshot, returns file path or base64.

Inputs: filename, response_format.

adb_screen_sizeGet Screen SizeA
Read-onlyIdempotent

Get screen resolution in pixels.

Inputs: no named parameters.

adb_shellExecute Android Shell CommandA
Destructive

Execute an Android shell command. ⚠️ Requires confirm=true.

Inputs: command (required), confirm (required), timeout.

adb_swipeSwipe on ScreenA

Swipe from (x1,y1) to (x2,y2) with optional duration (ms).

Inputs: x1 (required), y1 (required), x2 (required), y2 (required), +1 more.

adb_tapTap Screen at CoordinatesB

Tap screen at pixel coordinates (x, y).

Inputs: x (required), y (required).

adb_tap_textTap UI Element by TextA

Find UI element by text/ID/content-desc and tap its center. Regex partial match.

Inputs: text (required), type, wait_ms.

adb_termux_execExecute Command in TermuxA
Destructive

Execute a command in Termux bash. ⚠️ Requires confirm=true.

Inputs: command (required), confirm (required), timeout.

adb_textInput TextA

Type text into focused input. ASCII via key injection, Unicode via clipboard paste (Android 10+).

Inputs: text (required), method.

adb_ui_treeGet UI Element TreeA
Read-only

Get UI element tree (accessibility dump) with bounding boxes and positions.

Inputs: response_format, max_elements.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool targets a distinct ADB operation: app lifecycle, device info, input simulation, file transfer, and UI inspection. Even similar tools like adb_tap and adb_tap_text are clearly differentiated by targeting method (coordinates vs. element search). There is no ambiguity between tools.

    Naming Consistency5/5

    All tools follow the consistent pattern 'adb_' + descriptive snake_case noun or verb_noun. Examples: adb_app_info, adb_app_launch, adb_screenshot. No mixing of styles or vague prefixes.

    Tool Count5/5

    The 20 tools cover a comprehensive but focused set of ADB capabilities for mobile automation. The count is appropriate for the domain—neither sparse nor bloated. Each tool serves a clear purpose without redundancy.

    Completeness4/5

    Core workflows like app info/launch/stop, UI interaction (tap, swipe, text, key events), screenshots, and device info are covered. Missing common operations like file push, app install/uninstall, and logcat, but the set is sufficient for typical UI automation tasks.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • scrcpy-mcp

      JuanCF
      A
      license
      A
      quality
      C
      maintenance
      MCP server that gives AI agents full vision and control over Android devices via ADB and scrcpy. Supports screenshots, input, apps, UI automation, shell, files, and clipboard.
      38
      389 npm
      136
      MIT

    • android-mcp-server

      jaye773
      F
      license
      Not graded
      quality
      D
      maintenance
      A powerful MCP server that provides comprehensive Android device automation capabilities through ADB, enabling AI agents to interact with Android devices for testing, automation, and device control tasks.
      1
      -

    • android-adb-mcp

      qinxiandiqi
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that wraps Android ADB functionality into AI assistant tools, enabling device management, shell execution, file operations, app management, media capture, and log analysis via natural language.
      23 npm
      3
      MIT