使用说明

MCP安卓模拟器

一个模型上下文协议（MCP）服务器，使像Claude这样的AI助手能够通过ADB（Android调试桥）与Android设备和模拟器进行交互。

特性

截图：将设备屏幕捕获为base64图像
UI检查：获取UI层次结构（类似于DOM，但适用于Android）
触摸输入：点击、滑动、滚动、缩放、多次点击手势
文本输入：键入、清除、全选、在输入字段中设置文本
系统密钥：按返回、主页、回车、音量等。
应用程序管理：启动、安装、强制停止、清除数据
剪贴板：获取和设置剪贴板内容
设备控制：旋转屏幕，获取设备信息
日志：使用过滤器和日志级别访问logcat
等待并断言：等待元素、UI稳定性、测试断言
安全交互：点击避开系统栏，元素边界检测

需求

Node.js 18+
已安装ADB（安卓调试桥）
以下之一：
- 安卓工作室模拟器（AVD）
- Redroid（基于Docker的安卓系统）
- Genymotion
- 通过USB/WiFi连接的物理Android设备

安装

来自npm（推荐）

npm install -g mcp-android-emulator

来源

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

快速开始

1.确保ADB正常工作

adb devices
# Should show your device/emulator

2.添加到克劳德代码

claude mcp add android-emulator -- npx mcp-android-emulator

3.开始使用

问克劳德：“截取Android设备的屏幕截图”

配置

环境变量

变量	默认值	描述
`ADB_PATH`	`adb`	ADB可执行文件的路径
`SCREENSHOT_DIR`	`/tmp/android-screenshots`	临时截图目录

Claude代码集成

选项1:CLI命令

claude mcp add android-emulator -- npx mcp-android-emulator

选项2：手动配置

编辑 ~/.claude.json:

{
  "mcpServers": {
    "android-emulator": {
      "command": "npx",
      "args": ["mcp-android-emulator"],
      "env": {
        "ADB_PATH": "/path/to/adb"
      }
    }
  }
}

Claude桌面集成

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "android-emulator": {
      "command": "npx",
      "args": ["mcp-android-emulator"],
      "env": {
        "ADB_PATH": "/path/to/adb"
      }
    }
  }
}

可用工具（40个工具）

屏幕截图和用户界面

工具	说明
`screenshot`	将屏幕捕获为base64 PNG图像
`get_ui_tree`	获取带有坐标的UI元素层次结构
`get_all_text`	获取屏幕上所有可见的文本元素（用于调试）
`get_clickable_elements`	新获取所有带有text/id/坐标的可点击元素（当tap_text失败时非常有用）
`get_screen_size`	获取屏幕尺寸和密度
`get_focused_element`	获取当前关注元素的信息
`is_element_visible`	检查元素是否在屏幕上可见
`get_element_bounds`	获取元素的精确坐标
`assert_screen_contains`	断言文本可见（用于测试）

触摸交互

工具	说明
`tap`	点击特定坐标
`tap_text`	按文本查找元素并点击它
`tap_element`	按文本或资源id点击元素（更可靠）
`tap_safe`	点击避开系统导航栏
`double_tap`	双击坐标
`long_press`	长按可进入上下文菜单
`multi_tap`	同一位置有多个快速水龙头
`swipe`	在两点之间滑动
`scroll`	向上/下/左/右方向滚动
`scroll_to_text`	滚动直到文本可见
`drag`	拖放手势
`pinch_zoom`	捏住缩放手势（放大/缩小）

文本输入

工具	说明
`type_text`	在焦点输入中键入文本
`clear_input`	清晰聚焦的文本字段
`select_all`	选择焦点字段中的所有文本
`set_text`	清除并键入新文本（两者结合）
`get_focused_input_value`	新获取焦点输入的当前文本值
`is_keyboard_visible`	新检查软键盘当前是否可见

系统和密钥

工具	说明
`press_key`	按系统键（返回、主页、回车等）
`rotate_device`	旋转到纵向或横向
`set_clipboard`	将文本设置到设备剪贴板
`get_clipboard`	获取剪贴板内容

应用程序管理

工具	说明
`launch_app`	按程序包名称启动应用程序
`install_apk`	安装APK文件
`list_packages`	列出已安装的软件包
`clear_app_data`	清除应用程序数据
`force_stop`	强制停止应用程序
`get_current_activity`	获取当前重点活动

设备信息和日志

工具	说明
`device_info`	获取设备型号、Android版本、屏幕大小
`get_logs`	使用过滤器和日志级别获取logcat日志

等待并同步

工具	说明
`wait_for_element`	等待带有文本的元素出现
`wait_for_element_gone`	等待元素消失
`wait_for_ui_stable`	等待UI停止更改（动画后）

仿真器设置指南

选项1:安卓工作室模拟器（AVD）

最适合：在带显示器的机器上进行本地开发

# List available AVDs
emulator -list-avds

# Start emulator
emulator -avd YOUR_AVD_NAME

# Verify connection
adb devices

选项2:Redroid（Docker）-建议用于服务器

最适合：无头服务器、CI/CD、云VPS

Redroid在Docker容器中运行Android，不需要x86上的KVM。

# Run Redroid container
docker run -d --name redroid \
  --privileged \
  -p 5555:5555 \
  redroid/redroid:13.0.0-latest \
  androidboot.redroid_width=720 \
  androidboot.redroid_height=1280 \
  androidboot.redroid_dpi=320

# Connect ADB
adb connect localhost:5555

# Verify
adb devices

对于使用网络的应用程序（React Native、Expo等）：

# Forward ports from device to host
adb reverse tcp:8081 tcp:8081  # Metro bundler
adb reverse tcp:3000 tcp:3000  # API server

选项3：性别

最适合：本地开发，比AVD更快

下载自 genymotion.com
创建并启动虚拟设备
在设置中启用ADB网桥
连接： adb connect localhost:5555

选项4：物理设备

最适合：真实世界测试

USB连接：

在设备上启用开发人员选项
启用USB调试
通过USB连接
跑 adb devices

WiFi连接：

# First connect via USB, then:
adb tcpip 5555
adb connect DEVICE_IP:5555
# Disconnect USB

在云端/VPS服务器上运行

先决条件

Linux服务器（建议使用Ubuntu 20.04+）
Docker已安装
至少4GB RAM，2个CPU内核

逐步设置

1.安装ADB

# Ubuntu/Debian
sudo apt update
sudo apt install android-tools-adb

# Verify
adb version

2.运行Redroid

docker run -d --name redroid \
  --privileged \
  -p 5555:5555 \
  redroid/redroid:13.0.0-latest \
  androidboot.redroid_width=720 \
  androidboot.redroid_height=1280 \
  androidboot.redroid_dpi=320

3.连接ADB

adb connect localhost:5555
adb devices  # Should show "localhost:5555 device"

4.安装Node.js和MCP

# Install Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# Install MCP
npm install -g mcp-android-emulator

5.配置克劳德代码

claude mcp add android-emulator -- npx mcp-android-emulator

无头运行AVD（替代方案）

如果您有KVM支持：

# Install Android SDK
sudo apt install openjdk-11-jdk
wget https://dl.google.com/android/repository/commandlinetools-linux-latest.zip
# ... setup SDK ...

# Run emulator headless
emulator -avd YOUR_AVD \
  -no-window \
  -no-audio \
  -no-boot-anim \
  -gpu swiftshader_indirect \
  -memory 2048 \
  -cores 2

使用示例

配置后，让Claude：

"Take a screenshot of the Android device"

"Tap on the Login button"

"Type 'hello@example.com' in the email field and press Enter"

"Scroll down until you see 'Submit' and tap it"

"Launch the Chrome app and navigate to google.com"

"Get error logs from the last 100 lines"

"Wait for the loading spinner to disappear, then take a screenshot"

"Check if 'Welcome' text is visible on screen"

"Rotate the device to landscape mode"

自动化测试示例

"Test the login flow:
1. Take a screenshot of the initial state
2. Type 'testuser' in the username field
3. Type 'password123' in the password field
4. Tap the Login button
5. Wait for the UI to stabilize
6. Assert that 'Dashboard' is visible
7. Take a final screenshot"

故障排除

未找到ADB

# Check if ADB is installed
which adb

# If not found, install it
sudo apt install android-tools-adb  # Ubuntu/Debian
brew install android-platform-tools  # macOS

# Or set custom path
export ADB_PATH=/path/to/android-sdk/platform-tools/adb

未连接任何设备

# List devices
adb devices

# If using Redroid, connect explicitly
adb connect localhost:5555

# Check if emulator is fully booted
adb shell getprop sys.boot_completed  # Should return "1"

截图权限被拒绝

mkdir -p /tmp/android-screenshots
chmod 755 /tmp/android-screenshots

Redroid容器无法启动

# Check logs
docker logs redroid

# Ensure privileged mode
docker run --privileged ...

# Try different Android version
docker run ... redroid/redroid:11.0.0-latest

应用程序无法访问本地主机服务

# Forward ports from device to host
adb reverse tcp:8081 tcp:8081
adb reverse tcp:3000 tcp:3000

# Verify
adb reverse --list

更新日志

看更改日志.md 完整的历史。

v2.0.0（最新）--安全版本

消除了MCP工具表面的命令注入 （问题#1）。 ADB执行层重建于 child_process.execFile，以及每一个 LLM控制的输入现在在到达之前经过严格的zod同种异体动物设备外壳。
依赖关系被固定到精确的版本(npm audit 清洁）。
新 SECURITY.md 负责任的披露政策。
打破： 更严格的同种异体论者拒绝了一些以前接受的输入。看更改日志.md 移民笔记。

v1.4.0版本

新工具：
- get_clickable_elements -获取所有带有文本、资源id、类和坐标的可点击元素。有用的时候 tap_text 找不到元素。

v1.3.0版本

新工具：
- get_all_text -获取屏幕上所有可见的文本元素（对调试有用）
- is_keyboard_visible -检查软键盘当前是否可见
- get_focused_input_value -获取焦点输入字段的当前文本值
改进：
- wait_for_ui_stable -现在使用UI指纹而不是原始XML比较（更可靠）
- get_current_activity -与不同仿真器（AVD、Redroid、Genymotion等）兼容的多方法方法
- is_keyboard_visible -具有回退的多种检测方法

v1.2.3

更新文档，提供全面的设置指南
添加模拟器比较（AVD、Redroid、Genymotion、Physical）
添加了云/VPS部署说明
增加了故障排除部分

v1.2.2

固定的 set_clipboard 和 get_clipboard Redroid/Docker兼容性
用途 /data/local/tmp 作为回退路径

v1.2.0版本

新增14个工具：
- get_screen_size, is_element_visible, get_element_bounds
- scroll_to_text, wait_for_ui_stable, wait_for_element_gone
- multi_tap, pinch_zoom, tap_safe, tap_element
- set_clipboard, get_clipboard, rotate_device
- get_focused_element, assert_screen_contains

v1.1.0版本

添加 double_tap, drag, set_text, select_all, clear_input

v1.0.0

具有核心功能的初始版本

发展

# Clone repo
git clone https://github.com/Anjos2/mcp-android-emulator.git
cd mcp-android-emulator

# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run dev

许可证

MIT许可证-请参阅许可证了解详情。

贡献

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

贡献想法：

支持多个连接设备
屏幕录制
文件传输（推/拉）
网络仿真
电池/GPS模拟