Android Puppeteer

Android Puppeteer MCP Server is a lightweight, visual-first automation backend that lets AI agents interact with Android devices through intelligent UI element detection, touch interactions, text input, and optional video recording. It is designed to work with MCP-compatible clients, enabling seamless device automation workflows across multiple devices or emulators.

How to use

You interact with Android Puppeteer through an MCP client that communicates with the MCP server to discover UI elements, perform actions, and capture media. Use the available actions to locate interactive elements, simulate taps and gestures, input text, and navigate the UI. For multi-device scenarios, target a specific device so your automation steps apply only to that device.

Key workflows you can perform include taking annotated screenshots to identify element positions, tapping or long-pressing at specific coordinates, typing text into focused fields, swiping and scrolling to reveal off-screen elements, and recording a video of the automation session for documentation or testing.

If you work with multiple devices, list available devices and then target a chosen device for subsequent actions by specifying its identifier. This lets you run independent automation streams on different devices in parallel.

How to install

Prerequisites to run Android Puppeteer MCP Server are clearly defined so you can prepare your environment before starting.

Install prerequisites and set up the environment with these steps.

# Step 1: Clone the project repository
git clone https://github.com/pedro-rivas/android-puppeteer-mcp.git
cd android-puppeteer

# Step 2: Install dependencies
uv python install 3.10
uv sync

# Step 3: Prepare Android device
# Enable USB debugging on your Android device
# For emulator, ensure it's running
adb devices  # Verify device connection

# Step 4: Run the MCP server via stdio configuration (see MCP config below)
```} ,{

MCP configuration for the server

The MCP server is wired to run as a local process (stdio) that you launch from your MCP client configuration. The example below shows how to point your MCP launcher to the server executable and the script to start.

{
  "mcpServers": {
    "android-puppeteer": {
      "command": "path/to/uv",
      "args": [
        "--directory",
        "path/to/android-puppeteer",
        "run",
        "puppeteer.py"
      ]
    }
  }
}
````} ,{

Troubleshooting

Common issues you might encounter include device not found, permission errors for USB debugging, screenshot failures, and video recording issues. Start by verifying the ADB connection and ensuring the target device is authorized. If video recording fails, confirm scrcpy is installed and compatible with your device.

Project notes

The server exposes a set of tools for device management, visual interaction, navigation, input, and media capture. Use these capabilities to build robust automation sequences that can adapt to dynamic screens and evolving UI layouts.

Available tools

list_emulators

List all available Android emulators and devices with status and dimensions

get_device_dimensions

Retrieve screen dimensions for a specific device

get_ui_elements_info

Fetch detailed information about all interactive UI elements on screen

take_screenshot

Capture annotated screenshots with numbered overlays for UI elements

press

Tap at specific coordinates with optional long-press duration

long_press

Perform long press gestures on coordinates

press_back

Trigger the hardware back action

swipe

Swipe in a direction or along coordinates to navigate the UI

type_text

Type text into focused input fields with optional clearing