# 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
- `uiautomator2` compatible Android device (Android 4.4+)
## Installation
### From Source
1. Clone the repository:
```bash
git clone https://github.com/HadyAhmed00/Android-MCP.git
cd Android-MCP
```
2. Install dependencies:
```bash
pip install -e .
```
Or install manually:
```bash
pip install mcp uiautomator2 pillow ipykernel
```
## Quick Start
### 1. Start the MCP Server
**For emulator:**
```bash
python main.py --emulator
```
**For physical device:**
```bash
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:**
```json
{
"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 coordinate
- `y` (int): Y coordinate
**Example:**
```
Click on coordinates 540, 800
```
### 3. **Long-Click-Tool**
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
```
### 4. **Swipe-Tool**
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)
```
### 5. **Type-Tool**
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
```
### 6. **Drag-Tool**
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
```
### 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 extension
- `test_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