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

Related MCP server: DroidMind

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

F

license - not found

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

android-mcp