Android-MCP
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.
Features
- 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
Requirements
- Python 3.12+
- Android device or emulator running
- ADB (Android Debug Bridge) installed and configured
uiautomator2compatible Android device (Android 4.4+)
Installation
From Source
- Clone the repository:
git clone https://github.com/HadyAhmed00/Android-MCP.git
cd Android-MCP
- Install dependencies:
pip install -e .
Or install manually:
pip install mcp uiautomator2 pillow ipykernel
Quick Start
1. Start the MCP Server
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.
2. Configure with MCP Client
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"
]
}
}
}
Available Tools
The MCP server exposes 14 tools for controlling Android devices and recording test cases:
1. State-Tool
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
2. Click-Tool
Click on a specific coordinate on the screen.
Parameters:
x(int): X coordinatey(int): Y coordinate
Example:
Click on coordinates 540, 800
3. Long-Click-Tool
Long press (hold) on a specific coordinate.
Parameters:
x(int): X coordinatey(int): Y coordinate
Example:
Long click on 540, 800 for 2 seconds
4. Swipe-Tool
Perform a swipe gesture from one point to another.
Parameters:
x1(int): Starting X coordinatey1(int): Starting Y coordinatex2(int): Ending X coordinatey2(int): Ending Y coordinate
Example:
Swipe from top to bottom (refresh)
5. Type-Tool
Type text at a specific coordinate (automatically focuses the field).
Parameters:
text(str): Text to typex(int): X coordinatey(int): Y coordinateclear(bool, optional): Clear existing text before typing
Example:
Type "hello world" into the search field
6. Drag-Tool
Drag from one location and drop at another.
Parameters:
x1(int): Starting X coordinatey1(int): Starting Y coordinatex2(int): Ending X coordinatey2(int): Ending Y coordinate
Example:
Drag and drop item from position to trash
7. Press-Tool
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
8. Notification-Tool
Open the notification bar to access notifications.
Parameters: None
Example:
Open notification bar
9. Wait-Tool
Wait for a specified duration (useful for allowing apps to load).
Parameters:
duration(int): Seconds to wait
Example:
Wait for 2 seconds
10. Start-Recording-Tool
Start recording test actions for later export and playback.
Parameters: None
Example:
Start recording test actions
11. Stop-Recording-Tool
Stop recording test actions.
Parameters: None
Example:
Stop recording and finalize test
12. Export-Test-Script
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 extensiontest_name(str, optional): Custom test name for Python exports
Example:
Export recorded actions as a Python test script
13. Clear-Recording-Tool
Clear all recorded test actions.
Parameters: None
Example:
Clear the recording
14. Get-Recording-Stats-Tool
Get statistics about recorded test actions.
Parameters: None
Example:
Show recording statistics
Architecture
The project is organized into three main modules:
main.py
- Entry point that creates the FastMCP server
- Defines and exposes all 14 tools
- Handles command-line arguments (
--emulator) - Integrates test recording functionality
src/mobile/
- Mobile class: Manages device connection and state
- MobileState: Data class representing device state
- Captures screenshots and processes them
src/tree/
- Tree class: Parses Android UI XML hierarchy
- Extracts interactive elements (buttons, inputs, etc.)
- Generates annotated screenshots with numbered labels
- Helper utilities for coordinate extraction
src/recorder.py
- 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