Android Action MCP 服务器
英语 | 简体中文
一个可投入生产的模型上下文协议（MCP）服务器，它使像Claude Code这样的AI助手能够通过ADB与Android设备进行交互。
概述
这台MCP服务器提供了对Android设备的全面程序化访问，使AI助手能够：
- 从Android设备捕获UI树和屏幕截图
- 与用户界面元素进行交互（点击、输入、滑动、拖动）
- 浏览应用程序并执行操作
- 监控设备状态和网络活动
- 管理应用和权限
- 执行自动化工作流
该实现的灵感来源于：
- scrcpy（用于安卓设备的屏幕镜像和控制工具）为了高效的Android设备通信模式
- playwright-mcp 可以翻译为“Playwright MCP”（如果MCP是特定项目、模块或配置的名称），或者根据上下文具体解释，比如“Playwright的MCP（多配置/多平台/特定组件等，具体含义需根据上下文确定）”。在没有具体上下文的情况下，一个较为通用的翻译是“Playwright MCP（具体含义依上下文而定）”。如果MCP是一个已知术语或特定项目名，应直接使用其官方或公认的中文译名对于MCP工具设计模式
特点/特性
✅ 31款生产就绪工具（100% 完成）
一级：必备工具（11/11）
核心自动化功能：
- 安卓快照捕获结构化UI树（主要交互方式）
- 安卓截图捕获PNG格式的截图
- 安卓点击轻触、长按和双击手势
- android_type（可译为“安卓类型”或根据上下文具体指代，如“安卓手机型号”等）自动聚焦的文本输入
- 安卓导航启动应用程序并打开URL/深度链接
- Android返回导航返回按钮导航
- 按下Android键盘上的键硬件/软件关键事件
- 等待Android（系统/设备）等待用户界面条件或时间延迟
- 安卓滑动方向性滑动手势
- Android设备信息设备规格和功能
- 当前Android活动（或当前Android应用界面）获取前台应用程序和活动
第二级：重要工具（9/9）
全面的自动化功能：
- 安卓滚动滚动到元素可见
- 填写Android表单批量表单字段填充
- 安卓应用应用管理（列出/切换/最近/关闭）
- Android 关闭强制停止应用程序
- Android选择选项下拉选择器（下拉菜单）选择
- 安卓安装APK安装
- 授予Android权限运行时权限授予
- Android对话框处理多语言对话处理
- Android控制台消息Logcat消息检索
第三级：高级工具（6/6）
专业级高级用户功能：
- Android 拖放（或：安卓拖动）拖放手势
- Android评估安全执行shell命令
- 安卓调整大小屏幕方向控制
- 清除Android应用数据清除应用数据和缓存
- Android文件选择文件上传和选择
- Android网络请求网络活动监控
第4级：可选工具（5/5）
锦上添花的功能：
- Android_hover（安卓悬停/安卓悬浮）悬停交互（无障碍功能/触控笔）
- Android打开通知打开通知抽屉
- 打开Android快速设置打开快速设置面板
- 设置剪贴板（在Android系统中）设置剪贴板文本
- 获取Android剪贴板内容获取剪贴板文本
先决条件
- Go 1.21+（或更高版本） 安装好的
- ADB（Android调试桥） 已安装且已添加到系统路径(PATH)中
# macOS
brew install android-platform-tools
# Ubuntu/Debian
sudo apt-get install android-tools-adb- scrcpy 已安装（截图功能所需）
# macOS
brew install scrcpy
# Ubuntu/Debian
sudo apt install scrcpy
# Arch Linux
sudo pacman -S scrcpy
# Windows (via Scoop)
scoop install scrcpy为什么选择scrcpy？ 这个项目使用了scrcpy的高效屏幕截图方法来捕获截图，与原生方法相比，它在不同Android设备上的兼容性更好 adb shell screenrecap 命令。一些设备（例如，华为EMUI）不支持原生命令，但scrcpy具有通用性。
- 安卓设备 启用USB调试（API 21+）
- 启用开发者选项：设置 → 关于手机 → 连续点击“版本号”7次 - 启用USB调试：设置 → 开发者选项 → USB调试
安装
选项1：下载预编译二进制文件（推荐）
下载适用于您平台的最新版本：
可用平台：
- Linux：
android-mcp-server-linux-amd64，android-mcp-server-linux-arm64 - macOS（发音为 /ˈmækOS/）：
android-mcp-server-darwin-amd64（英特尔），android-mcp-server-darwin-arm64（Apple Silicon） - Windows：
android-mcp-server-windows-amd64.exe
下载后：
# macOS/Linux: Make executable
chmod +x android-mcp-server-*
# Verify with SHA256 checksum
sha256sum android-mcp-server-*
# Compare with checksums.txt from release
# Move to your preferred location (optional)
sudo mv android-mcp-server-* /usr/local/bin/android-mcp-server选项2：从源代码构建
# Clone the repository
git clone https://github.com/holocode-ai/android-action-mcp.git
cd android-action-mcp
# Build the server
go build -o android-mcp-server ./cmd/server
# Or use make
make build验证ADB连接
# Connect your Android device via USB
# Check device is recognized
adb devices
# Output should show your device:
# List of devices attached
# XXXXXXXXXXXXX device使用方法
使用 Claude Code（VS Code 扩展）
选项1：项目特定配置（推荐）
这个项目包含一个预配置的 .claude/mcp.json 文件。当你在Claude Code中打开这个项目时，MCP服务器将自动可用。
要在其他项目中使用，请复制示例配置：
# Copy the example config
cp mcp.json.example /path/to/your/project/.claude/mcp.json
# Update the command path to point to your build选项2：全局配置
添加到您的全局MCP设置中（~/.config/claude-code/mcp.json):
{
"mcpServers": {
"android-action": {
"command": "/absolute/path/to/android-mcp-server",
"env": {},
"disabled": false
}
}
}注将命令路径替换为您的绝对路径 android-mcp-server 二进制。
使用Cline/Claude Dev（VS Code扩展）
添加到您的MCP设置文件中（~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json （在 macOS 上）：
{
"mcpServers": {
"android-action": {
"command": "/absolute/path/to/android-mcp-server",
"args": [],
"disabled": false
}
}
}使用Claude桌面应用程序
在Claude Desktop的MCP配置中添加：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json Linux（发音类似“林克斯”）： ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"android-action": {
"command": "/absolute/path/to/android-mcp-server"
}
}
}添加配置后，重启Claude Desktop以加载MCP服务器。
与其他MCP客户端一起
服务器使用stdio传输方式，并且与任何MCP客户端兼容：
# Run directly (communicates via stdin/stdout)
./android-mcp-server
# Show help
./android-mcp-server --help工具参考
核心元素交互
Android快照
捕获结构化UI树——UI交互的主要方法。
参数： 无
返回： 带有元素、资源ID、文本、描述、边界和交互功能的格式化文本树
用法：
android_snapshot()安卓点击
在UI元素上执行点击操作。
参数：
element(字符串，必填)：可读的人类元素描述ref（字符串，必填）：来自快照的元素引用（资源ID、文本或内容描述）long_click（布尔值，可选）：执行长按操作而非轻触double_click（布尔值，可选）：执行双击操作
用法：
android_click({
element: "Login button",
ref: "loginButton"
})安卓类型
将文本输入到可编辑元素中。
参数：
element(字符串，必填项)：元素描述ref（字符串，必填）：来自快照的元素引用text(字符串，必需): 要输入的文本submit(布尔值，可选)：输入后按回车键clear_first(布尔值，可选)：在输入前清除现有文本
用法：
android_type({
element: "Username field",
ref: "usernameInput",
text: "user@example.com",
clear_first: true
})填写Android表单
一次性填写多个表单字段。
参数：
fields(数组，必需): 字段对象的数组，其中包含ref，type，和value
用法：
android_fill_form({
fields: [
{name: "Username", ref: "username", type: "textbox", value: "user@example.com"},
{name: "Password", ref: "password", type: "textbox", value: "secret123"},
{name: "Remember me", ref: "rememberMe", type: "checkbox", value: "true"}
]
})导航与应用控制
安卓导航
启动应用或打开URL/深度链接。
参数：
package（字符串，可选）：应用包名activity(字符串，可选)：要启动的具体活动url(字符串，可选)：要打开的URL或深度链接
用法：
// Launch app
android_navigate({package: "com.android.chrome"})
// Open URL
android_navigate({url: "https://example.com"})安卓应用
管理正在运行的应用程序。
参数：
action(字符串，必填): "列表", "切换", "最近", "关闭"package（字符串，可选）：用于切换/关闭操作的包名
用法：
// List running apps
android_apps({action: "list"})
// Switch to app
android_apps({action: "switch", package: "com.android.chrome"})屏幕分析
安卓截图
捕获PNG格式的屏幕截图。
参数：
filename(字符串，可选)：文件名（默认：screenshot-{时间戳}.png）save_path(字符串，可选)：保存截图的目录
用法：
android_screenshot({
filename: "app-screenshot.png",
save_path: "./screenshots"
})手势与滚动
安卓滑动
执行滑动手势。
参数：
direction（字符串，必填）：“上”，“下”，“左”，“右”element(字符串，可选)：在其中滑动的元素ref（字符串，可选）：元素引用distance（字符串，可选）："短"、"中"、"长"speed（字符串，可选）："快速"，"中等"，"缓慢"
用法：
android_swipe({direction: "up", distance: "medium"})安卓滚动
在容器中滚动，直到元素可见。
参数：
container（字符串，必填）：可滚动容器的描述container_ref(字符串，必填)：容器引用（必须是\[可滚动的\]）target_element（字符串，可选）：要滚动到的元素direction(字符串，可选)：滚动方向max_scrolls（数字，可选）：最大滚动尝试次数
用法：
android_scroll({
container: "Product list",
container_ref: "productList",
target_element: "Item 50"
})等待与同步
等待Android（系统/设备）
等待条件满足或进行时间延迟。
参数：
text(字符串，可选)：等待文本出现text_gone(字符串，可选)：等待文本消失element（字符串，可选）：等待元素出现element_gone（字符串，可选）：等待元素消失time（数字，可选）：等待N秒timeout（数字，可选）：最长等待时间（默认：30）
用法：
// Wait for loading to finish
android_wait_for({text_gone: "Loading..."})
// Wait 2 seconds
android_wait_for({time: 2})调试与设备状态
Android设备信息
获取设备信息。
参数： 无
返回值： 设备型号、Android版本、屏幕分辨率、DPI（每英寸点数）、SDK版本
用法：
android_device_info()Android控制台消息
获取 logcat 消息。
参数：
only_errors(布尔值，可选)：仅过滤错误/警告tag（字符串，可选）：按 logcat 标签过滤max_lines(数字，可选)：限制输出行数（默认：100）
用法：
android_console_messages({only_errors: true, max_lines: 50})Android网络请求
监控网络活动。
参数：
package(字符串，可选)：按包名过滤duration(数字，可选)：捕获时长（以秒为单位）（默认：10）
用法：
android_network_requests({package: "com.example.app", duration: 5})文件与权限管理
安卓安装
安装APK包。
参数：
apk_path（字符串，必填）：APK文件的本地路径replace(布尔值，可选)：替换现有应用（默认：true）grant_permissions（布尔值，可选）：授予所有权限（默认：false）
用法：
android_install({
apk_path: "./app-debug.apk",
grant_permissions: true
})授予Android权限
授予应用程序运行时权限。
参数：
package（字符串，必填）：应用包名permission（字符串，必填）：权限名称
用法：
android_grant_permission({
package: "com.example.app",
permission: "android.permission.CAMERA"
})如需完整的工具文档，请参阅 CLAUDE.md（文件名，可译为“克劳德.md”或保持原样，具体取决于上下文是否需要翻译文件名）。
建筑学
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ AI Assistant │ ◄─MCP─► │ Go MCP Server │ ◄─ADB─► │ Android Device │
│ (Claude Code) │ │ (This Project) │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
├─ 31 Tools │
├─ ADB Communication │
└─ Device Control │组件
- MCP服务器层 (
internal/mcp/)
- 使用官方Go SDK实现MCP协议 - 为AI客户提供31种工具 - 处理标准I/O传输
- 亚洲开发银行通信层 (
internal/adb/)
- 管理ADB与Android设备的连接 - 执行用于设备控制的shell命令 - 基于scrcpy已验证的架构
- 工具层 (
internal/tools/）
- 实现单个MCP工具 - UI树解析与元素选择 - 坐标计算与手势处理
发展
项目结构
android-action-mcp/
├── cmd/
│ └── server/ # Main entry point
├── internal/
│ ├── mcp/ # MCP server implementation
│ ├── tools/ # 31 MCP tool implementations
│ ├── adb/ # ADB communication layer
│ └── uitree/ # UI tree parsing and selector
├── android-test-app/ # Custom test application
├── go.mod
├── Makefile
├── CLAUDE.md # Developer documentation
└── README.md # This file建筑
# Build
make build
# Run tests
make test
# Clean build artifacts
make clean测试
所有31种工具都已在真实硬件上进行了测试：
- 测试设备华为ANA-AN00，搭载Android 12（SDK 31），屏幕分辨率为1080x2340
- 测试应用自定义MCP测试应用（com.test.mcptest）
- 测试覆盖率100%的已实施工具均通过真实设备交互进行了测试
故障排除
没有设备连接
# Error: no Android devices connected
# Solution: Check USB connection and USB debugging is enabled
adb devices
# If device shows as "unauthorized", check device screen for authorization dialog未找到ADB
# Error: failed to initialize ADB
# Solution: Install ADB and ensure it's in PATH
which adb
# macOS
brew install android-platform-tools
# Linux
sudo apt-get install android-tools-adb权限被拒绝
# Linux: ADB may need udev rules for USB access
# Create file: /etc/udev/rules.d/51-android.rules
# Content: SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", MODE="0666", GROUP="plugdev"
# Replace XXXX with your device's vendor ID (from lsusb)
sudo udevadm control --reload-rules
sudo udevadm trigger未找到 scrcpy
# Error: scrcpy not found or not in PATH
# Solution: Install scrcpy (required for screenshot functionality)
# macOS
brew install scrcpy
# Ubuntu/Debian
sudo apt install scrcpy
# Verify installation
which scrcpy
scrcpy --version特定工具的问题
- 安卓悬停可能无法在仅支持触摸屏的设备上工作（预期行为）
- 设置Android剪贴板可能在某些制造商（例如，华为EMUI）的设备上无法正常工作
- 安卓截图必须提供
save_path参数（base64 编码超出 MCP 令牌限制）
参考文献
- 模型上下文协议
- MCP Go SDK
- scrcpy（一个用于在电脑上控制安卓手机的开源工具） - Android屏幕镜像（ADB通信的灵感来源）
- Android ADB 文档
- playwright-mcp 翻译为中文是“playwright 多进程控制（或：多客户端进程）”。不过，具体翻译可能根据上下文有所调整，因为“mcp”在这里可能是一个特定项目、工具或框架的缩写，没有统一的翻译标准。在一般情况下，可以理解为与 Playwright 相关的多进程管理或控制功能 - 参考实现
许可证
MIT 许可证 - 详情请参见 LICENSE 文件
贡献
欢迎贡献！请随时提交拉取请求。
项目状态
✅ 准备就绪，可投入生产 - 所有31个计划中的工具均已在真实硬件上实现并测试。
该服务器通过MCP协议提供全面的Android自动化功能，使AI助手能够执行复杂的测试和自动化工作流程。