使用说明

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 as Python (ADB or uiautomator2), pytest, JSON, or human-readable format

Requirements

An Android device or emulator with USB debugging enabled
uv (it fetches Python for you)

That's it. ADB is bundled, and the Portal helper app is installed onto the device automatically on first use.

Installation

claude mcp add android -- uvx --from git+https://github.com/HadyAhmed00/Android-MCP@main android-mcp-portal --emulator

Drop --emulator for a physical device, or pass --device <id> to pick one.

For any other MCP client, use the equivalent config:

{
  "mcpServers": {
    "android-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/HadyAhmed00/Android-MCP@main",
        "android-mcp-portal",
        "--emulator"
      ]
    }
  }
}

Note: the PyPI release is not published yet, so install straight from GitHub as above. Once android-mcp-portal is on PyPI this shortens to claude mcp add android -- uvx android-mcp-portal@latest --emulator.

What happens on first use

ADB — uses adb from your PATH, or falls back to the copy bundled with the adbutils dependency, so no Android SDK install is required.
Portal app — the fast state-reading backend needs the Portal app on the device. If it is missing, the server downloads the pinned APK, installs it, and enables its accessibility service, then verifies with a ping.
If any of that fails (some OEMs block enabling accessibility services over ADB), the server prints manual steps and keeps working on the slower UIAutomator2 backend.

Run it yourself any time with:

uvx --from git+https://github.com/HadyAhmed00/Android-MCP@main android-mcp-portal setup --device emulator-5554

or ask the agent to call the Setup-Device tool.

Flags: --skip-bootstrap never touches the device, --portal-apk <path> installs a local APK. The downloaded APK is cached per-user; set ANDROID_MCP_CACHE_DIR to move that cache.

From source (development)

git clone https://github.com/HadyAhmed00/Android-MCP.git
cd Android-MCP
uv sync
python main.py --emulator          # or: python -m android_mcp --emulator

Available Tools

The MCP server exposes 19 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

9b. Click-By-Label

Tap an element by its label index from the most recent State-Tool output. Preferred over raw coordinates. Indices are positional and only valid against the latest state — they shift whenever the screen changes.

Parameters:

label (int): Index from the --- Interactive Elements --- list

9c. Setup-Device

Install the Portal helper app and enable its accessibility service. Use it when State-Tool is slow or the fast backend is unavailable.

Parameters:

force (bool, optional): Reinstall even if the app already works

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

使用说明

Android-MCP

Features

Requirements

Installation

What happens on first use

From source (development)

Available Tools

1. State-Tool

2. Click-Tool

3. Long-Click-Tool

4. Swipe-Tool

5. Type-Tool

6. Drag-Tool

7. Press-Tool

8. Notification-Tool

9. Wait-Tool

9b. Click-By-Label

9c. Setup-Device

10. Start-Recording-Tool

11. Stop-Recording-Tool

12. Export-Test-Script

13. Clear-Recording-Tool

14. Get-Recording-Stats-Tool

Architecture

main.py

src/mobile/

src/tree/

src/recorder.py

相关 MCP

小度智能终端

智能家居设备控制服务器

iPhone自动化服务器

智能家居控制MCP服务器

ADB控制服务

Windows桌面自动化工具包

`main.py`

`src/mobile/`

`src/tree/`

`src/recorder.py`