MCP Android Emulator

MCP安卓模拟器

](https://www.npmjs.com/package/mcp-android-emulator) 

一个模型上下文协议（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设备的屏幕截图”

______________________________________________________________________

配置

环境变量

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个工具）

屏幕截图和用户界面

触摸交互

文本输入

系统和密钥

应用程序管理

设备信息和日志

等待并同步

______________________________________________________________________

仿真器设置指南

选项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更快

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

选项4：物理设备

最适合：真实世界测试

USB连接：

1. 在设备上启用开发人员选项
2. 启用USB调试
3. 通过USB连接
4. 跑 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模拟

相关项目

• 模型上下文协议
• 安卓调试桥（ADB）
• 克劳德代码
• Redroid