Android Emulator

npm version License: MIT

A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Android devices and emulators via ADB (Android Debug Bridge).

Features

• Screenshots: Capture device screen as base64 images
• UI Inspection: Get UI hierarchy (like DOM but for Android)
• Touch Input: Tap, swipe, scroll, pinch zoom, multi-tap gestures
• Text Input: Type, clear, select all, set text in input fields
• System Keys: Press BACK, HOME, ENTER, VOLUME, etc.
• App Management: Launch, install, force stop, clear data
• Clipboard: Get and set clipboard content
• Device Control: Rotate screen, get device info
• Logs: Access logcat with filters and log levels
• Wait & Assert: Wait for elements, UI stability, assertions for testing
• Safe Interactions: Tap avoiding system bars, element bounds detection

Requirements

• Node.js 18+
• ADB (Android Debug Bridge) installed
• One of the following:
  • Android Studio Emulator (AVD)
  • Redroid (Docker-based Android)
  • Genymotion
  • Physical Android device via USB/WiFi

Installation

From npm (Recommended)

npm install -g mcp-android-emulator

From source

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

Quick Start

1. Ensure ADB is working

adb devices
# Should show your device/emulator

2. Add to Claude Code

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

3. Start using

Ask Claude: "Take a screenshot of the Android device"

---

Configuration

Environment Variables

Variable	Default	Description
ADB_PATH	adb	Path to ADB executable
SCREENSHOT_DIR	/tmp/android-screenshots	Directory for temporary screenshots

Claude Code Integration

Option 1: CLI command

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

Option 2: Manual configuration

Edit ~/.claude.json:

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

Claude Desktop Integration

Add to claude_desktop_config.json:

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

---

Available Tools (40 tools)

Screen Capture & UI

Tool	Description
screenshot	Capture screen as base64 PNG image
get_ui_tree	Get UI element hierarchy with coordinates
get_all_text	Get all visible text elements on screen (for debugging)
get_clickable_elements	NEW Get all clickable elements with text/id/coordinates (useful when tap_text fails)
get_screen_size	Get screen dimensions and density
get_focused_element	Get info about currently focused element
is_element_visible	Check if element is visible on screen
get_element_bounds	Get exact coordinates of an element
assert_screen_contains	Assert text is visible (for testing)

Touch Interactions

Tool	Description
tap	Tap at specific coordinates
tap_text	Find element by text and tap it
tap_element	Tap element by text or resource-id (more reliable)
tap_safe	Tap avoiding system navigation bars
double_tap	Double tap at coordinates
long_press	Long press for context menus
multi_tap	Multiple rapid taps at same position
swipe	Swipe between two points
scroll	Scroll in a direction (up/down/left/right)
scroll_to_text	Scroll until text is visible
drag	Drag gesture for drag & drop
pinch_zoom	Pinch zoom gesture (zoom in/out)

Text Input

Tool	Description
type_text	Type text into focused input
clear_input	Clear focused text field
select_all	Select all text in focused field
set_text	Clear and type new text (combines both)
get_focused_input_value	NEW Get current text value of focused input
is_keyboard_visible	NEW Check if soft keyboard is currently visible

System & Keys

Tool	Description
press_key	Press system key (BACK, HOME, ENTER, etc.)
rotate_device	Rotate to portrait or landscape
set_clipboard	Set text to device clipboard
get_clipboard	Get clipboard content

App Management

Tool	Description
launch_app	Launch app by package name
install_apk	Install APK file
list_packages	List installed packages
clear_app_data	Clear app data
force_stop	Force stop an app
get_current_activity	Get currently focused activity

Device Info & Logs

Tool	Description
device_info	Get device model, Android version, screen size
get_logs	Get logcat logs with filters and log levels

Wait & Sync

Tool	Description
wait_for_element	Wait for element with text to appear
wait_for_element_gone	Wait for element to disappear
wait_for_ui_stable	Wait for UI to stop changing (after animations)

---

Emulator Setup Guides

Option 1: Android Studio Emulator (AVD)

Best for: Local development on machines with display

# List available AVDs
emulator -list-avds

# Start emulator
emulator -avd YOUR_AVD_NAME

# Verify connection
adb devices

Option 2: Redroid (Docker) - Recommended for Servers

Best for: Headless servers, CI/CD, cloud VPS

Redroid runs Android in a Docker container without requiring KVM on x86.

# 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

For apps using network (React Native, Expo, etc.):

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

Option 3: Genymotion

Best for: Local development, faster than AVD

1. Download from genymotion.com
2. Create and start a virtual device
3. Enable ADB bridge in settings
4. Connect: adb connect localhost:5555

Option 4: Physical Device

Best for: Real-world testing

USB Connection:

1. Enable Developer Options on device
2. Enable USB Debugging
3. Connect via USB
4. Run adb devices

WiFi Connection:

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

---

Running on Cloud/VPS Servers

Prerequisites

• Linux server (Ubuntu 20.04+ recommended)
• Docker installed
• At least 4GB RAM, 2 CPU cores

Step-by-Step Setup

1. Install ADB

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

# Verify
adb version

2. Run 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. Connect ADB

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

4. Install Node.js and 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. Configure Claude Code

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

Running AVD Headless (Alternative)

If you have KVM support:

# 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

---

Usage Examples

Once configured, ask Claude to:

"Take a screenshot of the Android device"

"Tap on the Login button"

"Type '[email protected]' 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"

Automated Testing Example

"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"

---

Troubleshooting

ADB not found

# 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

No devices connected

# 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"

Permission denied on screenshots

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

Redroid container won't start

# Check logs
docker logs redroid

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

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

Apps can't reach localhost services

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

# Verify
adb reverse --list

---

Changelog

See CHANGELOG.md for the full history.

v2.0.0 (Latest) — Security release

• Eliminated command injection across the MCP tool surface (issue #1). The ADB execution layer was rebuilt on child_process.execFile, and every LLM-controlled input now passes through strict zod allowlists before reaching the device shell.
• Dependencies pinned to exact versions (npm audit clean).
• New SECURITY.md with responsible disclosure policy.
• Breaking: stricter allowlists reject some inputs previously accepted. See CHANGELOG.md for migration notes.

v1.4.0

• New tools:
  • get_clickable_elements - Get all clickable elements with text, resource-id, class, and coordinates. Useful when tap_text fails to find an element.

v1.3.0

• New tools:
  • get_all_text - Get all visible text elements on screen (useful for debugging)
  • is_keyboard_visible - Check if soft keyboard is currently visible
  • get_focused_input_value - Get current text value of focused input field
• Improvements:
  • wait_for_ui_stable - Now uses UI fingerprint instead of raw XML comparison (more reliable)
  • get_current_activity - Multi-method approach for compatibility with different emulators (AVD, Redroid, Genymotion, etc.)
  • is_keyboard_visible - Multiple detection methods with fallbacks

v1.2.3

• Updated documentation with comprehensive setup guides
• Added emulator comparison (AVD, Redroid, Genymotion, Physical)
• Added cloud/VPS deployment instructions
• Added troubleshooting section

v1.2.2

• Fixed set_clipboard and get_clipboard for Redroid/Docker compatibility
• Uses /data/local/tmp as fallback path

v1.2.0

• Added 14 new tools:
  • 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

• Added double_tap, drag, set_text, select_all, clear_input

v1.0.0

• Initial release with core functionality

---

Development

# 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

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Ideas for contributions:

• Support for multiple connected devices
• Screen recording
• File transfer (push/pull)
• Network simulation
• Battery/GPS simulation

Related Projects

• Model Context Protocol
• Android Debug Bridge (ADB)
• Claude Code
• Redroid