readme.md•7.59 kB
[](https://www.python.org/downloads/) [](https://github.com/nim444/mcp-android-server-python/actions/workflows/ci.yml) [](https://codecov.io/gh/nim444/sdet-django-api) [](https://github.com/astral-sh/ruff)
[](https://opensource.org/licenses/MIT)
# MCP Android Agent
This project provides an **MCP (Model Context Protocol)** server for automating Android devices using [uiautomator2](https://github.com/openatx/uiautomator2). It's designed to be easily plugged into AI agents like GitHub Copilot Chat, Claude, or Open Interpreter to control Android devices through natural language.
## Quick Demo
----
## Requirements
- Python 3.13 or higher
- Android Debug Bridge (adb) installed and in PATH
- Connected Android device with USB debugging enabled
- [uiautomator2](https://github.com/openatx/uiautomator2) compatible Android device
## Features
- Start, stop, and manage apps by package name
- Retrieve installed apps and current foreground app
- Tap, swipe, scroll, drag, and perform UI interactions
- Get device info, screen resolution, battery status, and more
- Capture screenshots or last toast messages
- Programmatically unlock, wake, or sleep the screen
- Clear app data and wait for activities
- Includes a health check and `adb` diagnostic tool
## Use Cases
Perfect for:
- AI agents that need to interact with real devices
- Remote device control setups
- Automated QA tools
- Android bot frameworks
- UI testing and automation
- Device management and monitoring
## Installation
### 1. Clone the repo
```bash
git clone https://github.com/nim444/mcp-android.git
cd mcp-android
```
### 2. Create and activate virtual environment
```bash
# Using uv (https://github.com/astral-sh/uv)
uv venv
source .venv/bin/activate # On Windows: .venv\\Scripts\\activate
```
### 3. Install dependencies
```bash
uv pip install
```
## Running the Server
### Option 1: Using uvicorn (Recommended)
```bash
uvicorn server:app --factory --host 0.0.0.0 --port 8000
```
### Option 2: Using MCP stdio (For AI agent integration)
```bash
python server.py
```
## Usage
An MCP client is needed to use this server. The Claude Desktop app is an example of an MCP client. To use this server with Claude Desktop:
### Locate your Claude Desktop configuration file
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
### Add the Android MCP server configuration to the mcpServers section
```json
{
"mcpServers": {
"mcp-android": {
"type": "stdio",
"command": "bash",
"args": [
"-c",
"cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
]
}
}
}
```
Replace `/path/to/mcp-adb` with the absolute path to where you cloned this repository. For example: `/Users/username/Projects/mcp-adb`
### Using with VS Code
You can also use this MCP server with VS Code's agent mode (requires VS Code 1.99 or newer). To set up:
1. Create a `.vscode/mcp.json` file in your workspace:
```json
{
"servers": {
"mcp-android": {
"type": "stdio",
"command": "bash",
"args": [
"-c",
"cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
]
}
}
}
```
Replace `/path/to/mcp-adb` with the absolute path to where you cloned this repository.
After adding the configuration, you can manage the server using:
- Command Palette → `MCP: List Servers` to view and manage configured servers
- Command Palette → `MCP: Start Server` to start the server
- The server's tools will be available in VS Code's agent mode chat
## UI Inspector
The project includes support for uiauto.dev, a powerful UI inspection tool for viewing and analyzing your device's interface structure.
1. Install the UI inspector:
```bash
uv pip install uiautodev
```
2. Start the inspector:
```bash
uiauto.dev
```
3. Open your browser and navigate to <https://uiauto.dev>
## Available MCP Tools
| Tool Name | Description |
|-----------------------|--------------------------------------------------------------------------|
| `mcp_health` | Check if the MCP server is running properly |
| `connect_device` | Connect to an Android device and get basic info |
| `get_installed_apps` | List all installed apps with version and package info |
| `get_current_app` | Get info about the app currently in the foreground |
| `start_app` | Start an app by its package name |
| `stop_app` | Stop an app by its package name |
| `stop_all_apps` | Stop all currently running apps |
| `screen_on` | Turn on the screen |
| `screen_off` | Turn off the screen |
| `get_device_info` | Get detailed device info: serial, resolution, battery, etc. |
| `press_key` | Simulate hardware key press (e.g. `home`, `back`, `menu`, etc.) |
| `unlock_screen` | Unlock the screen (turn on and swipe if necessary) |
| `check_adb` | Check if ADB is installed and list connected devices |
| `wait_for_screen_on` | Wait asynchronously until the screen is turned on |
| `click` | Tap on an element by `text`, `resourceId`, or `description` |
| `long_click` | Perform a long click on an element |
| `send_text` | Input text into currently focused field (optionally clearing before) |
| `get_element_info` | Get info on UI elements (text, bounds, clickable, etc.) |
| `swipe` | Swipe from one coordinate to another |
| `wait_for_element` | Wait for an element to appear on screen |
| `screenshot` | Take and save a screenshot from the device |
| `scroll_to` | Scroll until a given element becomes visible |
| `drag` | Drag an element to a specific screen location |
| `get_toast` | Get the last toast message shown on screen |
| `clear_app_data` | Clear user data/cache of a specified app |
| `wait_activity` | Wait until a specific activity appears |
| `dump_hierarchy` | Dump the UI hierarchy of the current screen as XML |
---
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.