android-mcp

Android MCP Server

A lightweight MCP (Model Context Protocol) server for Android operating system automation. This server provides tools to interact directly with Android devices, enabling automated testing, app interaction, and device control.

Features

Device Control: Click, long click, swipe, drag, and type on Android devices
State Management: Get device state with optional visual screenshots
Navigation: Press hardware buttons and access notifications
Automation: Wait functionality for timing control
Emulator Support: Works with both physical devices and Android emulators

Prerequisites

Python 3.13 or higher
uv package manager
Android device or emulator with USB debugging enabled
ADB (Android Debug Bridge) installed and accessible

Installation

1. Install uv (if not already installed)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: using pip
pip install uv

2. Set up the project

# Navigate to the android MCP directory
cd mcp/android

# Install dependencies
uv sync

# Activate the virtual environment (optional, uv run handles this automatically)
source .venv/bin/activate

3. Verify installation

# Test the server
uv run main.py --help

Usage

Running the server

For physical devices:

uv run main.py

For Android emulator:

uv run main.py --emulator

Device Setup

Enable Developer Options on your Android device:
- Go to Settings > About phone
- Tap "Build number" 7 times
Enable USB Debugging:
- Go to Settings > Developer options
- Enable "USB debugging"
Connect device and verify ADB connection:
adb devices

MCP Server Configuration

Add the following configuration to your MCP client settings (e.g., Claude Desktop, Cline, etc.):

{
  "mcpServers": {
    "android-mcp": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/agent/mcp/android && source .venv/bin/activate && uv run main.py --emulator"
      ],
      "alwaysAllow": [
        "State-Tool",
        "Click-Tool",
        "Type-Tool",
        "Swipe-Tool"
      ]
    }
  }
}

Note: Update the path in the configuration to match your actual project location.

Configuration Options

For physical devices: Remove the --emulator flag from the args
Custom device: Add --device <device_id> to specify a particular device
alwaysAllow: Pre-approve specific tools to avoid repeated permission prompts

Available Tools

Tool	Description	Parameters
Click-Tool	Click on specific coordinates	`x: int, y: int`
State-Tool	Get device state with optional screenshot	`use_vision: bool = false`
Long-Click-Tool	Long press on coordinates	`x: int, y: int, duration: int`
Swipe-Tool	Swipe between coordinates	`x1: int, y1: int, x2: int, y2: int`
Type-Tool	Type text at coordinates	`text: str, x: int, y: int, clear: bool = false`
Drag-Tool	Drag and drop between coordinates	`x1: int, y1: int, x2: int, y2: int`
Press-Tool	Press hardware buttons	`button: str`
Notification-Tool	Access notification panel	None
Wait-Tool	Wait for specified duration	`duration: int`

Troubleshooting

Common Issues

Device not found:
- Ensure USB debugging is enabled
- Check adb devices output
- Try different USB cables/ports
Permission denied:
- Allow USB debugging permission on device
- Check device authorization in adb devices
Connection timeout:
- Restart ADB: adb kill-server && adb start-server
- Reconnect device
Python version issues:
- Ensure Python 3.13+ is installed
- Use uv python install 3.13 if needed

Emulator Setup

If using Android emulator:

Start Android emulator (usually accessible as emulator-5554)
Verify connection: adb connect emulator-5554
Use --emulator flag when running the server

Development

Project Structure

mcp/android/
├── README.md
├── pyproject.toml
├── main.py           # MCP server entry point
├── src/
│   ├── mobile/       # Device interaction logic
│   └── tree/         # UI tree parsing and state management
└── .venv/           # Virtual environment

Dependencies

mcp: Model Context Protocol framework
uiautomator2: Android device automation
pillow: Image processing for screenshots
ipykernel: Jupyter kernel support

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

A lightweight MCP server for Android operating system automation. This server provides tools to interact directly with Android devices and app interaction with control

Related MCP Servers

Android MCP Server
minhalvp
-
security
A
license
-
quality
A server enabling programmatic control over Android devices through ADB, providing capabilities like screenshot capture, UI layout analysis, and package management that can be accessed by MCP clients like Claude Desktop.
Last updated -
503
Apache 2.0
DroidMind
hyperb1iss
A
security
A
license
A
quality
A Model Context Protocol (MCP) server that enables AI assistants to control and interact with Android devices, allowing for device management, app debugging, system analysis, and UI automation through natural language commands.
Last updated -
8
207
Apache 2.0
UIAutomator2 MCP Server
GitDzreal93
-
security
F
license
-
quality
A FastMCP framework-based server providing Android device automation control capabilities, enabling UI interactions, device management, and application control through natural language.
Last updated -
7
Apktool MCP Server
zinja-coder
A
security
A
license
A
quality
An MCP server that integrates with Apktool to provide live reverse engineering support for Android applications using Claude and other LLMs through the Model Context Protocol.
Last updated -
13
195
Apache 2.0

View all related MCP servers

android-mcp

Android MCP Server

Features

Prerequisites

Installation

1. Install uv (if not already installed)

2. Set up the project

3. Verify installation

Usage

Running the server

For physical devices:

For Android emulator:

Device Setup

MCP Server Configuration

Configuration Options

Available Tools

Troubleshooting

Common Issues

Emulator Setup

Development

Project Structure

Dependencies

Related MCP Servers

Android MCP Server

DroidMind

UIAutomator2 MCP Server

Apktool MCP Server

New MCP Servers

MCP directory API