mcp-name: io.github.pedro-rivas/android-puppeteer-mcp

Android Puppeteer

Android Puppeteer is a lightweight, visual-first MCP (Model Context Protocol) server that enables AI agents to interact with Android devices through intelligent UI element detection and automated interactions. Built on uiautomator2, it provides comprehensive Android automation capabilities including visual element detection, touch interactions, text input, and video recording.

🎥 Watch the demo in action

Features

• Visual Element Detection Automatically detects and annotates interactive UI elements with numbered overlays for precise targeting.

• Comprehensive Touch Interactions Support for tap, long press, swipe, scroll, and drag gestures with coordinate-based precision.

• Multi-Device Support Connect to multiple Android devices or emulators simultaneously with device-specific targeting.

• Video Recording Integration Built-in screen recording capabilities using scrcpy for documentation and testing workflows.

• Real-Time UI Analysis Live UI hierarchy parsing and element information extraction for dynamic interaction strategies.

• MCP Protocol Integration Seamless integration with Claude Desktop and other MCP-compatible AI platforms.

Supported Operating Systems

• Android 10+
• Windows, macOS, Linux (host systems)

Installation

Prerequisites

• Python 3.10+
• uiautomator2
• Android 10+ (Emulator or Physical Device)
• ADB (Android Debug Bridge)
• scrcpy (for video recording features)

Getting Started

1. Clone the repository

git clone https://github.com/pedro-rivas/android-puppeteer-mcp.git
cd android-puppeteer

2. Install dependencies

uv python install 3.10
uv sync

3. Setup Android device

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

4. Connect to the MCP server

5. Locate your Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

6. Add the following JSON to your Claude Desktop config:

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

   Replace:

   • path/to/uv with the actual path to your uv executable
   • path/to/android-puppeteer with the absolute path to where you have cloned this repo

7. Restart Claude Desktop

Restart your Claude Desktop. You should see "android-puppeteer" listed as an available integration.

Available Tools

Android Puppeteer provides the following tools for comprehensive Android device interaction:

Device Management

• list_emulators: List all available Android emulators and devices with their status and dimensions
• get_device_dimensions: Get the screen dimensions of a specific Android device
• get_ui_elements_info: Get detailed information about all interactive UI elements on screen

Visual Interaction

• take_screenshot: Capture annotated screenshots with numbered UI element overlays
• press: Tap on specific coordinates with optional long press duration
• long_press: Perform long press gestures on specifi

... View full README on GitHub