Android-MCP is a lightweight, open-source tool that bridge between AI agents and Android devices. Running as an MCP server, it lets LLM agents perform real-world tasks such as app navigation, UI interaction and automated QA testing without relying on traditional computer-vision pipelines or preprogramed scripts.

• Direct Device Control: Click, swipe, drag, type, and press buttons on Android devices
• UI State Inspection: Get device state with UI hierarchy and optional annotated screenshots
• MCP Integration: Works with any MCP-compatible client (Claude Desktop, VS Code, etc.)
• Emulator Support: Works with Android emulators (tested on emulator-5554)
• Physical Device Support: Connect to real Android devices via ADB
• Vision Capabilities: Generate annotated screenshots with numbered UI elements for vision-based AI agents
• Test Recording: Record user interactions and export as executable test scripts (Python, JSON, or human-readable format)
• Test Script Export: Export recorded tests in multiple formats for CI/CD integration

• Python 3.12+
• Android device or emulator running
• ADB (Android Debug Bridge) installed and configured
• uiautomator2 compatible Android device (Android 4.4+)

1. Clone the repository:

git clone https://github.com/HadyAhmed00/Android-MCP.git
cd Android-MCP

2. Install dependencies:

pip install -e .

Or install manually:

pip install mcp uiautomator2 pillow ipykernel

For emulator:

python main.py --emulator

For physical device:

python main.py

The server will connect to your Android device via ADB and start listening for MCP client connections.

To use this with Claude Code or other MCP clients, add the following to your MCP configuration:

Example MCP Config:

{
  "mcpServers": {
    "android-mcp": {
      "command": "python",
      "args": [
        "/path/to/Android-MCP/main.py",
        "--emulator"
      ]
    }
  }
}

The MCP server exposes 14 tools for controlling Android devices and recording test cases:

Get the current state of the device including UI hierarchy and optional screenshot.

Parameters:

• use_vision (bool, optional): Include annotated screenshot with labeled UI elements

Example:

Get device state with screenshot

Click on a specific coordinate on the screen.

Parameters:

• x (int): X coordinate
• y (int): Y coordinate

Example:

Click on coordinates 540, 800

Long press (hold) on a specific coordinate.

Parameters:

• x (int): X coordinate
• y (int): Y coordinate

Example:

Long click on 540, 800 for 2 seconds

Perform a swipe gesture from one point to another.

Parameters:

• x1 (int): Starting X coordinate
• y1 (int): Starting Y coordinate
• x2 (int): Ending X coordinate
• y2 (int): Ending Y coordinate

Example:

Swipe from top to bottom (refresh)

Type text at a specific coordinate (automatically focuses the field).

Parameters:

• text (str): Text to type
• x (int): X coordinate
• y (int): Y coordinate
• clear (bool, optional): Clear existing text before typing

Example:

Type "hello world" into the search field

Drag from one location and drop at another.

Parameters:

• x1 (int): Starting X coordinate
• y1 (int): Starting Y coordinate
• x2 (int): Ending X coordinate
• y2 (int): Ending Y coordinate

Example:

Drag and drop item from position to trash

Press device buttons (home, back, power, volume, etc.).

Parameters:

• button (str): Button name (back, home, power, volume_up, volume_down)

Example:

Press the back button

Open the notification bar to access notifications.

Parameters: None

Example:

Open notification bar

Wait for a specified duration (useful for allowing apps to load).

Parameters:

• duration (int): Seconds to wait

Example:

Wait for 2 seconds

Start recording test actions for later export and playback.

Parameters: None

Example:

Start recording test actions

Stop recording test actions.

Parameters: None

Example:

Stop recording and finalize test

Export recorded test actions as an executable test script in multiple formats.

Parameters:

• format (str): Export format - 'python', 'json', or 'readable' (default: 'python')
• filename (str, optional): Custom filename without extension
• test_name (str, optional): Custom test name for Python exports

Example:

Export recorded actions as a Python test script

Clear all recorded test actions.

Parameters: None

Example:

Clear the recording

Get statistics about recorded test actions.

Parameters: None

Example:

Show recording statistics

The project is organized into three main modules:

• Entry point that creates the FastMCP server
• Defines and exposes all 14 tools
• Handles command-line arguments (--emulator)
• Integrates test recording functionality

• Mobile class: Manages device connection and state
• MobileState: Data class representing device state
• Captures screenshots and processes them

• Tree class: Parses Android UI XML hierarchy
• Extracts interactive elements (buttons, inputs, etc.)
• Generates annotated screenshots with numbered labels
• Helper utilities for coordinate extraction

• TestRecorder class: Records user actions during testing
• TestAction: Data class representing a single action
• Supports multiple export formats (Python, JSON, Readable)
• Generates fully independent ADB-based Python scripts
• Exports structured test data for CI/CD integration