安卓-MCP服务器

Name: 安卓-MCP服务器
Author: jduartedj

作者：jduartedj2 星标更新：2025-11-13

安装使用来源：spider==github.com

项目介绍

Android MCP Server

一个提供全面Android设备控制的Model Context Protocol (MCP)服务器，通过Scrcpy提供了22个强大的工具，用于UI自动化、屏幕截图和超快速H.264流传输。

功能

📸 屏幕截图：从Android设备捕获屏幕截图
👆 触摸与手势：模拟触摸、长按、滑动和多点交互
⌨️ 文本输入与按键事件：直接文本输入和按键事件模拟（2个工具）
- 发送按键事件（如HOME、BACK、ENTER等）
- 直接在焦点字段中输入文本
🔧 通用ADB命令：执行带有自定义参数的任何ADB命令（1个工具）
- 代理可以完全自由地运行自定义ADB操作
- 访问所有ADB功能（如logcat、shell命令、包管理器等）
🎯 UIAutomator：完整的UI层次检查和元素交互（10个工具）
- 转储完整的XML UI层次结构
- 通过资源ID或文本查找元素
- 单击、双击、长按元素
- 在输入字段中设置或清除文本
- 切换复选框
- 等待元素出现
- 在特定元素内滚动
⚡ Scrcpy流传输：超快的H.264视频流传输（4个工具）
- 开始/停止H.264视频流（约2秒设置，小于50毫秒帧轮询）
- 捕获单帧（100-300毫秒）或最新流帧（小于50毫秒）
- 比屏幕截图捕捉快得多
🚀 应用管理：启动应用并列出已安装的包
🔌 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 Code（参见下面的VS Code集成）

安装

npm install
npm run build

使用方法

单独运行服务器

node dist/index.js

配置

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

ADB_PATH：ADB可执行文件的自定义路径（默认：使用系统PATH或自动下载）
DEVICE_SERIAL：要针对的具体设备序列号（默认：第一个可用设备）

VS Code集成

添加到VS Code GitHub Copilot

要在VS Code中使用此MCP服务器与GitHub Copilot：

打开VS Code设置（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。在Windows上使用双反斜杠。

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

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

重新加载VS Code或重启GitHub Copilot扩展

验证集成

添加服务器后：

在VS Code中打开GitHub Copilot聊天
输入@workspace，您应该能看到Android MCP工具
尝试询问：“拍摄我的Android设备的屏幕截图”
Copilot将使用适当的工具来捕获屏幕

Copilot示例提示

一旦集成，您可以询问GitHub Copilot：

“拍摄我的Android设备的屏幕截图”
“开始流式传输我的设备屏幕以进行实时监控”
“获取流中的最新帧”
“在我的手机上坐标500,1000处点击”
“向上滑动我的Android屏幕”
“按下我的设备上的返回按钮”
“发送主页键事件”
“在当前字段中输入'hello world'”
“按下回车键提交表单”
“使用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（可选）：触摸持续时间（单位：毫秒，默认：100毫秒快速点击，大于100毫秒长按）
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.apps.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 - 电源按钮

用例：

导航（HOME，BACK）
提交表单（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"]
  }
}

读取logcat：

{
  "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"]
  }
}

UIAutomator工具（10个）

9. `android_uiautomator_dump`

转储当前屏幕的完整UI层次结构作为XML，用于检查和元素识别。

参数：

deviceSerial（可选）：通过序列号指定目标设备

返回值：完整的XML UI层次结构，可以解析以找到元素资源ID和属性。

性能：约500-800毫秒

用例：

检查应用UI结构
查找自动化所需的元素资源ID
理解视图层次结构

示例：

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

10. `android_uiautomator_find`

通过资源ID或文本内容使用UIAutomator查找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（必需）：复选

安卓-MCP服务器

项目介绍

Android MCP Server

功能

先决条件

快速开始

安装

使用方法

单独运行服务器

配置

VS Code集成

添加到VS Code GitHub Copilot

验证集成

Copilot示例提示

所有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

UIAutomator工具（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

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`