MCP Android Emulator

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

Related MCP server: Android Mobile MCP

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

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

Touch Interactions

Text Input

System & Keys

App Management

Device Info & Logs

Wait & Sync

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

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