使用说明

安卓MCP服务器

一种模型上下文协议（MCP）服务器，提供全面的Android设备控制 22个强大的工具 通过Scrcpy实现UI自动化、屏幕截图和超高速H.264流媒体。

特性

📸 截图：从Android设备捕获屏幕截图
👆 触摸和手势：模拟触摸、长按、滑动和多点交互
⌨️ 文本输入和关键事件：直接文本输入和关键事件模拟（2个工具）
- 发送关键事件（主页、后退、回车等）
- 直接在焦点字段中输入文本
🔧 通用ADB命令：使用自定义参数执行任何ADB命令（1个工具）
- 代理商运行自定义ADB操作的完全灵活性
- 访问所有ADB功能（logcat、shell命令、包管理器等）
🎯 UI 自动化：完整的UI层次结构检查和元素交互（10个工具）
- 转储完整的XML UI层次结构
- 按资源ID或文本查找元素
- 点击、双击、长按元素
- 设置/清除输入字段中的文本
- 切换复选框
- 等待元素出现
- 在特定元素内滚动
⚡ Scrcpy流媒体：超高速H.264视频流（4个工具）
- 启动/停止H.264视频流（~2s设置，<50ms帧轮询）
- 捕获单帧（100-300ms）或最新流帧（<50ms）
- 比截图快得多
🚀 应用程序管理：启动应用程序并列出已安装的软件包
🔌 ADB集成：与Android调试桥直接集成
⚡ 自动下载：自动从官方来源下载ADB和Scrcpy

先决条件

Node.js 18或更高版本
通过USB连接的Android设备，启用USB调试，或运行模拟器

注： ADB（Android调试桥）和Scrcpy是可选的——如果需要，服务器会在首次使用时自动从官方来源下载它们。

快速开始

克隆和构建

git clone https://github.com/jduartedj/android-mcp-server.git
cd android-mcp-server
npm install
npm run build

测试服务器
```
node dist/index.js
```
如果需要，服务器将启动并自动下载ADB/Scrcpy。
添加到VS代码 （参见 VS代码集成在......下面

安装

npm install
npm run build

用法

独立运行服务器

node dist/index.js

配置

服务器支持以下环境变量：

ADB_PATH：ADB可执行文件的自定义路径（默认：使用系统path或自动下载）
DEVICE_SERIAL：目标的特定设备序列号（默认值：第一个可用设备）

VS代码集成

添加到VS代码GitHub副本

要在VS代码中将此MCP服务器与GitHub Copilot一起使用：

打开VS代码设置 （Ctrl+或Cmd+）
搜索MCP 或导航到： GitHub Copilot > Chat > MCP Servers
编辑MCP配置 点击“在settings.json中编辑”
添加Android MCP服务器 根据您的配置：

{
  "github.copilot.chat.mcp.servers": {
    "android-mcp-server": {
      "command": "node",
      "args": ["F:\\android-mcp-server\\dist\\index.js"],
      "env": {
        "ADB_PATH": "",
        "DEVICE_SERIAL": ""
      }
    }
  }
}

注：替换 F:\\android-mcp-server\\dist\\index.js 与您的实际绝对路径 dist/index.js 文件。在Windows上使用双反斜杠。

替代方案：使用npx （如果发布到npm）：

{
  "github.copilot.chat.mcp.servers": {
    "android-mcp-server": {
      "command": "npx",
      "args": ["-y", "android-mcp-server"]
    }
  }
}

重新加载VS代码 或重新启动GitHub Copilot扩展

验证集成

添加服务器后：

在VS代码中打开GitHub Copilot聊天
类型 @workspace 您应该看到可用的Android MCP工具
试着问：“给我的安卓设备截图”
副驾驶将使用适当的工具捕捉屏幕

副驾驶提示示例

集成后，您可以询问GitHub Copilot：

“截取我的Android设备的屏幕截图”
“开始流式传输我的设备屏幕以进行实时监控”
“从流中获取最新帧”
在我的手机上点击坐标5001000
“在我的Android屏幕上向上滑动”
“按我设备上的后退按钮”
“发送主页密钥事件”
“在当前字段中键入‘hello world’”
“按enter键提交表单”
“使用ADB获取设备电池状态”
“读取logcat输出进行调试”
“清除com.example.app的应用程序数据”
“列出所有已安装的软件包”
“启动Chrome应用程序”
“找到登录按钮并单击它”
“在电子邮件字段中填写user@example.com"
“转储当前屏幕的UI层次结构”
“长按菜单按钮”
“在设置列表中向下滚动”
“切换启用通知复选框”
“等待加载指示器消失”

全部22个MCP工具

基本工具（5）

1. `android_screenshot`

从Android设备捕获屏幕截图。

参数：

outputPath （可选）：保存截图的本地路径。如果没有提供，则返回base64编码的图像。
deviceSerial （可选）：按序列号定位特定设备

演出每次捕获约1-2秒

例子：

{
  "name": "android_screenshot",
  "arguments": {
    "outputPath": "./screenshot.png"
  }
}

2. `android_touch`

在特定屏幕坐标处模拟触摸事件。支持快速点击和长按。

参数：

x （必填）：X坐标
y （必填）：Y坐标
duration （可选）：触摸持续时间（毫秒）（默认值：点击100ms，长按>100ms）
deviceSerial （可选）：按序列号定位特定设备

演出立即

示例-快速点击：

{
  "name": "android_touch",
  "arguments": { "x": 500, "y": 1000, "duration": 100 }
}

示例-长按：

{
  "name": "android_touch",
  "arguments": { "x": 500, "y": 1000, "duration": 2000 }
}

3. `android_swipe`

在两个坐标之间执行滑动手势。

参数：

startX （必填）：起始X坐标
startY （必填）：起始Y坐标
endX （必填）：结束X坐标
endY （必填）：结束Y坐标
duration （可选）：滑动持续时间（毫秒）（默认值：300）
deviceSerial （可选）：按序列号定位特定设备

演出立即

例子：

{
  "name": "android_swipe",
  "arguments": {
    "startX": 500, "startY": 1500, "endX": 500, "endY": 500, "duration": 300
  }
}

4. `android_launch_app`

按软件包名称启动Android应用程序。

参数：

packageName （必填）：应用程序的包名称（例如，com.example.app、com.google.android.app.maps）
deviceSerial （可选）：按序列号定位特定设备

演出约1-2秒

例子：

{
  "name": "android_launch_app",
  "arguments": { "packageName": "com.example.app" }
}

5. `android_list_packages`

列出Android设备上已安装的软件包，并可选择过滤。

参数：

filter （可选）：搜索包名过滤器（不区分大小写）
deviceSerial （可选）：按序列号定位特定设备

演出中等（检索完整包列表）

示例-列出所有包：

{
  "name": "android_list_packages",
  "arguments": {}
}

示例-过滤器包：

{
  "name": "android_list_packages",
  "arguments": { "filter": "google" }
}

文本输入和关键事件工具（2）

6. `android_input_text`

通过ADB在Android设备上的当前焦点字段中输入文本。

参数：

text （必填）：要输入的文本。空间会自动处理。
deviceSerial （可选）：按序列号定位特定设备

演出立即

使用案例：

无需UIAutomator即可快速输入文本
当元素资源ID未知时输入文本
简单的表单填写
命令行样式文本输入

例子：

{
  "name": "android_input_text",
  "arguments": {
    "text": "user@example.com"
  }
}

7. `android_send_key_event`

向Android设备发送关键事件（例如，HOME、BACK、ENTER）。

参数：

keyCode （必填）：关键事件代码。可以是键名（例如，KEYEVENT_HOME、KEYEVENT_BACK）或数字代码（例如，3表示HOME，4表示BACK）
deviceSerial （可选）：按序列号定位特定设备

演出立即

通用密钥代码：

KEYEVENT_HOME 或 3 -主页按钮
KEYEVENT_BACK 或 4 -后退按钮
KEYEVENT_ENTER 或 66 -输入/返回键
KEYEVENT_DEL 或 67 -删除密钥
KEYEVENT_MENU 或 82 -菜单按钮
KEYEVENT_VOLUME_UP 或 24 -音量增大
KEYEVENT_VOLUME_DOWN 或 25 -音量降低
KEYEVENT_POWER 或 26 -电源按钮

使用案例：

导航（主页、返回）
提交表格（ENTER）
控制装置功能（音量、功率）
键盘快捷键

例子：

{
  "name": "android_send_key_event",
  "arguments": {
    "keyCode": "KEYEVENT_BACK"
  }
}

通用ADB命令工具（1）

8. `android_execute_command`

使用自定义参数执行通用ADB命令。这个强大的工具为代理提供了完全的灵活性，可以使用自己的参数运行任何ADB命令。

参数：

args （必填）：ADB命令参数数组（例如，[“shell”、“pm”、“list”、“packages”]）
deviceSerial （可选）：按序列号定位特定设备

演出因命令而异

退货： 命令执行时的stdout和stderr

使用案例：

执行自定义shell命令
访问logcat进行调试
管理软件包（安装、卸载、清除数据）
查询设备属性
文件操作（推送、拉取）
网络操作（端口转发）
特定工具未涵盖的任何ADB功能

常见示例：

列出所有包：

{
  "name": "android_execute_command",
  "arguments": {
    "args": ["shell", "pm", "list", "packages"]
  }
}

获取设备属性：

{
  "name": "android_execute_command",
  "arguments": {
    "args": ["shell", "getprop", "ro.build.version.release"]
  }
}

阅读日志：

{
  "name": "android_execute_command",
  "arguments": {
    "args": ["logcat", "-d", "-s", "MyTag:V"]
  }
}

清除应用程序数据：

{
  "name": "android_execute_command",
  "arguments": {
    "args": ["shell", "pm", "clear", "com.example.app"]
  }
}

获取电池信息：

{
  "name": "android_execute_command",
  "arguments": {
    "args": ["shell", "dumpsys", "battery"]
  }
}

将文件推送到设备：

{
  "name": "android_execute_command",
  "arguments": {
    "args": ["push", "/local/path/file.txt", "/sdcard/file.txt"]
  }
}

安装APK：

{
  "name": "android_execute_command",
  "arguments": {
    "args": ["install", "-r", "/path/to/app.apk"]
  }
}

端口转发：

{
  "name": "android_execute_command",
  "arguments": {
    "args": ["forward", "tcp:8080", "tcp:8080"]
  }
}

UI自动化工具（10）

9. `android_uiautomator_dump`

将当前屏幕的完整UI层次结构转储为XML，以便检查和元素标识。

参数：

deviceSerial （可选）：按序列号定位特定设备

退货： 完整的XML UI层次结构，可以解析以查找元素资源ID和属性。

演出 ~500-800ms

使用案例：

检查应用程序UI结构
查找用于自动化的元素资源ID
了解视图层次结构

例子：

{
  "name": "android_uiautomator_dump",
  "arguments": {}
}

10. `android_uiautomator_find`

使用UIAutomator按资源ID或文本内容查找UI元素。

参数：

resourceId （可选）：要搜索的资源ID（例如com.example.app:ID/button_submit）
text （可选）：要搜索的文本内容
deviceSerial （可选）：按序列号定位特定设备

演出快速

示例-按资源ID查找：

{
  "name": "android_uiautomator_find",
  "arguments": { "resourceId": "com.example.app:id/email_input" }
}

示例-按文本查找：

{
  "name": "android_uiautomator_find",
  "arguments": { "text": "Submit" }
}

11. `android_uiautomator_click`

按资源ID单击UI元素。

参数：

resourceId （必填）：要单击的元素的资源ID
deviceSerial （可选）：按序列号定位特定设备

演出立即

例子：

{
  "name": "android_uiautomator_click",
  "arguments": { "resourceId": "com.example.app:id/button_submit" }
}

12. `android_uiautomator_double_click`

按资源ID双击UI元素。

参数：

resourceId （必填）：元素的资源ID
deviceSerial （可选）：按序列号定位特定设备

演出立即

例子：

{
  "name": "android_uiautomator_double_click",
  "arguments": { "resourceId": "com.example.app:id/text_field" }
}

13. `android_uiautomator_long_click`

按资源ID长按UI元素。

参数：

resourceId （必填）：元素的资源ID
deviceSerial （可选）：按序列号定位特定设备

演出立即

例子：

{
  "name": "android_uiautomator_long_click",
  "arguments": { "resourceId": "com.example.app:id/menu_item" }
}

14. `android_uiautomator_set_text`

按资源ID在UI元素上设置文本。首先自动清除现有文本。

参数：

resourceId （必填）：元素的资源ID
text （必填）：要设置的文本
deviceSerial （可选）：按序列号定位特定设备

演出立即

例子：

{
  "name": "android_uiautomator_set_text",
  "arguments": {
    "resourceId": "com.example.app:id/email_input",
    "text": "user@example.com"
  }
}

15. `android_uiautomator_clear_text`

按资源ID清除UI元素中的文本。

参数：

resourceId （必填）：元素的资源ID
deviceSerial （可选）：按序列号定位特定设备

演出立即

例子：

{
  "name": "android_uiautomator_clear_text",
  "arguments": { "resourceId": "com.example.app:id/search_input" }
}

16. `android_uiautomator_toggle_checkbox`

按资源ID切换复选框元素。

参数：

resourceId （必填）：复选框的资源ID
deviceSerial （可选）：按序列号定位特定设备

演出立即

例子：

{
  "name": "android_uiautomator_toggle_checkbox",
  "arguments": { "resourceId": "com.example.app:id/agree_checkbox" }
}

17. `android_uiautomator_wait`

等待具有超时支持的资源ID显示UI元素。

参数：

resourceId （必需）：要等待的资源ID
timeoutMs （可选）：最大等待时间（毫秒）（默认值：5000）
deviceSerial （可选）：按序列号定位特定设备

演出可配置（最多超时）

例子：

{
  "name": "android_uiautomator_wait",
  "arguments": {
    "resourceId": "com.example.app:id/loading_indicator",
    "timeoutMs": 10000
  }
}

18. `android_uiautomator_scroll_in_element`

在特定的可滚动UI元素内滚动。

参数：

resourceId （必填）：可滚动元素的资源ID
direction （必填）：滚动方向（上、下、左、右）
distance （可选）：滚动距离（像素）（默认值：500）
deviceSerial （可选）：按序列号定位特定设备

演出立即

例子：

{
  "name": "android_uiautomator_scroll_in_element",
  "arguments": {
    "resourceId": "com.example.app:id/list_view",
    "direction": "down",
    "distance": 500
  }
}

Scrcpy流媒体工具（4）

Scrcpy流媒体使用H.264视频编码提供超快速帧捕获，非常适合实时监控、快速截图序列或连续帧轮询。

19. `android_start_scrcpy_stream`

使用Scrcpy从Android设备初始化H.264视频流。

参数：

deviceSerial （可选）：按序列号定位特定设备
bitrate （可选）：视频比特率，单位为Mbps（默认值：4）
fps （可选）：每秒帧数（默认值：60）

演出约2秒设置，之后每帧轮询<50ms

优势：

超快速帧捕获（<50ms，而截图为1-2s）
带有预缓冲帧的连续流媒体
非常适合实时监控
H.264压缩减少了带宽

例子：

{
  "name": "android_start_scrcpy_stream",
  "arguments": {
    "bitrate": 4,
    "fps": 30
  }
}

20. `android_get_latest_frame`

从活动的Scrcpy流中轮询最新帧。

参数：

deviceSerial （可选）：按序列号定位特定设备
outputPath （可选）：将帧保存到文件，否则返回base64

演出每帧<50ms（由于预缓冲流）

使用案例：

实时监控
快速截图序列
连续帧轮询
流媒体可视化

例子：

{
  "name": "android_get_latest_frame",
  "arguments": {
    "outputPath": "./current_frame.png"
  }
}

21. `android_stop_scrcpy_stream`

停止活动的Scrcpy H.264流。

参数：

deviceSerial （可选）：按序列号定位特定设备

例子：

{
  "name": "android_stop_scrcpy_stream",
  "arguments": {}
}

22. `android_capture_frame_scrcpy`

使用Scrcpy捕获单个帧，而不启动持久流。

参数：

deviceSerial （可选）：按序列号定位特定设备
outputPath （可选）：将帧保存到文件，否则返回base64
bitrate （可选）：视频比特率，单位为Mbps（默认值：4）

演出 100-300ms（比截图快，比流媒体慢）

使用案例：

一次性帧捕捉
当流媒体开销不合理时
单帧比较
轻量级捕获操作

例子：

{
  "name": "android_capture_frame_scrcpy",
  "arguments": {
    "outputPath": "./single_frame.png"
  }
}

性能比较

工具	目的	速度	最佳用途
`android_screenshot`	基本捕捉	1-2s	简单截图，初步检查
`android_capture_frame_scrcpy`	单个Scrcpy帧	100-300ms	比屏幕截图更快的一次性捕获
`android_start_scrcpy_stream`	初始化流	~2s设置	实时监控工作流
`android_get_latest_frame`	轮询流	<50ms	快速帧序列，实时应用程序
`android_touch`	点击/长按	即时	UI交互
`android_swipe`	滑动手势	立即	导航、滚动
`android_input_text`	直接文本输入	即时	通过ADB快速输入文本
`android_send_key_event`	关键事件	即时	导航（主页、后退、回车）
`android_execute_command`	通用ADB	多种多样	自定义ADB操作，完全灵活
`android_uiautomator_dump`	UI检查	500-800ms	元素发现
`android_uiautomator_find`	元素搜索	快速	定位特定元素
`android_uiautomator_*`	元素交互	即时	表单填写，UI自动化

常见用例

1.自动化测试

1. Dump UI hierarchy to find element IDs
2. Click buttons and input text using resource IDs
3. Use streaming to verify visual changes in real-time
4. Scroll and navigate through the app

2.实时监控

1. Start Scrcpy stream (one-time ~2s setup)
2. Poll latest frames continuously (<50ms each)
3. Process frames for visual analysis
4. Stop stream when done

3.快速帧捕获序列

1. Start Scrcpy stream
2. Get latest frame multiple times (much faster than screenshot)
3. Process frame sequence for animation/comparison
4. Stop stream

4.表单填充（WebView或Native）

1. Find form fields by resource ID or text
2. Clear existing text
3. Set new text values
4. Toggle checkboxes and radio buttons
5. Click submit button

5.多设备自动化

使用 deviceSerial 针对特定设备的参数：

1. List connected devices via ADB
2. Specify device serial for each tool call
3. Automate workflows on multiple devices in parallel
4. Useful for device farms and testing labs

6.应用程序发现

1. List all packages (potentially 100+)
2. Filter packages by name (e.g., "google", "com.example")
3. Launch apps by package name
4. Perfect for discovering available apps on the device

ADB和Scrcpy设置

自动安装

服务器会自动从官方来源下载和安装：

安卓调试桥：来自Android平台工具
屏幕镜像：来自官方发布

下载的工具存储在 ~/.android-mcp-server/platform-tools/

手动安装（可选）

窗户：

choco install adb
choco install scrcpy

macOS：

brew install android-platform-tools
brew install scrcpy

Linux（Ubuntu/Debian）：

sudo apt-get install android-tools-adb scrcpy

在Android上启用USB调试

首选设置 → 关于手机
轻按 版本号 7次启用开发人员选项
首选设置 → 开发人员选项
启用 USB调试
通过USB连接设备并接受调试提示

验证连接

adb devices

您应该看到您的设备已列出。

故障排除

问题	解决方案
“未找到Android设备”	确保设备已通过USB连接，并且已启用USB调试。跑 `adb devices` 以验证。
找不到UIAutomator元素	使用 `android_uiautomator_dump` 检查XML并验证资源ID是否存在。
Scrcpy流无法启动	请确保安装了Scrcpy或允许自动下载完成。检查设备是否已连接。
“未找到ADB”错误	运行服务器一次以自动下载ADB，或手动安装平台工具。
触摸坐标不起作用	验证坐标是否在屏幕范围内。使用屏幕截图确定正确的坐标。
应用程序启动失败	使用验证包名称是否正确 `android_list_packages`。如果不确定，请尝试过滤。
流媒体帧速度较慢	降低比特率/fps或使用单帧 `android_capture_frame_scrcpy` 用于一次性捕获。

高级模式

实时视觉监控

1. android_start_scrcpy_stream (2s setup)
2. Loop: android_get_latest_frame (<50ms each)
3. Process frames for ML/analysis
4. android_stop_scrcpy_stream when done

使用快速框架进行压力测试

1. Start stream
2. Perform action on device
3. Capture 10+ frames in rapid succession (<50ms each)
4. Compare frame changes for regression detection

多步表单自动化

1. android_uiautomator_dump (find all fields)
2. For each field:
   - android_uiautomator_find (locate)
   - android_uiautomator_set_text (fill)
3. android_uiautomator_click (submit)
4. android_uiautomator_wait (result screen)
5. android_screenshot (verify)

设备场并行测试

1. Get device list
2. For each device:
   - Specify deviceSerial in all tool calls
   - Run automation sequence
   - Compare results across devices

建筑

服务器使用模型上下文协议来公开Android设备控件：

ADB包装器 (src/adb-wrapper.ts)：设备通信，自动下载ADB
Scrcpy集成 (src/adb-wrapper.ts)：H.264流媒体、帧轮询
UI自动机方法 (src/adb-wrapper.ts)：完全XML转储，元素交互
工具操作员 (src/handlers.ts)：所有19个工具操作
MCP服务器 (src/index.ts)：通过模型上下文协议公开所有工具

支持的Android版本

Android 5.0+（API 21+级）
Scrcpy流媒体：通过ADB的Android 5.0+，在7.0上最佳+

发展

# Install dependencies
npm install

# Build
npm run build

# Watch mode (if supported)
npm run watch

添加新工具

要添加新工具，请执行以下操作：

实现方法 在 src/adb-wrapper.ts
机具处理程序 在 src/handlers.ts
注册工具 在 src/index.ts 包含名称、描述和模式
构建和测试 服务器正在运行

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。

使用说明

安卓MCP服务器

特性

先决条件

快速开始

安装

用法

独立运行服务器

配置

VS代码集成

添加到VS代码GitHub副本

验证集成

副驾驶提示示例

全部22个MCP工具

基本工具（5）

1. android_screenshot

2. android_touch

3. android_swipe

4. android_launch_app

5. android_list_packages

文本输入和关键事件工具（2）

6. android_input_text

7. android_send_key_event

通用ADB命令工具（1）

8. android_execute_command

UI自动化工具（10）

9. android_uiautomator_dump

10. android_uiautomator_find

11. android_uiautomator_click

12. android_uiautomator_double_click

13. android_uiautomator_long_click

14. android_uiautomator_set_text

15. android_uiautomator_clear_text

16. android_uiautomator_toggle_checkbox

17. android_uiautomator_wait

18. android_uiautomator_scroll_in_element

Scrcpy流媒体工具（4）

19. android_start_scrcpy_stream

20. android_get_latest_frame

21. android_stop_scrcpy_stream

22. android_capture_frame_scrcpy

性能比较

常见用例

1.自动化测试

2.实时监控

3.快速帧捕获序列

4.表单填充（WebView或Native）

5.多设备自动化

6.应用程序发现

ADB和Scrcpy设置

自动安装

手动安装（可选）

在Android上启用USB调试

验证连接

故障排除

高级模式

实时视觉监控

使用快速框架进行压力测试

多步表单自动化

设备场并行测试

建筑

支持的Android版本

发展

添加新工具

许可证

贡献

相关 MCP

小度智能终端

智能家居设备控制服务器

iPhone自动化服务器

智能家居控制MCP服务器

ADB控制服务

Windows桌面自动化工具包

1. `android_screenshot`

2. `android_touch`

3. `android_swipe`

4. `android_launch_app`

5. `android_list_packages`

6. `android_input_text`

7. `android_send_key_event`

8. `android_execute_command`

9. `android_uiautomator_dump`

10. `android_uiautomator_find`

11. `android_uiautomator_click`

12. `android_uiautomator_double_click`

13. `android_uiautomator_long_click`

14. `android_uiautomator_set_text`

15. `android_uiautomator_clear_text`

16. `android_uiautomator_toggle_checkbox`

17. `android_uiautomator_wait`

18. `android_uiautomator_scroll_in_element`

19. `android_start_scrcpy_stream`

20. `android_get_latest_frame`

21. `android_stop_scrcpy_stream`

22. `android_capture_frame_scrcpy`