# Android MCP Server

> 🤖 An MCP (Model Context Protocol) server designed for Android development, enabling AI assistants to directly control Android devices for screenshots, UI analysis, app management, and more.

[中文文档](./README_zh.md)

---

## Table of Contents

- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Tools](#tools)
- [Debugging](#debugging)
- [References](#references)

---

## Introduction

This project is built on the [FastMCP](https://github.com/jlowin/fastmcp) framework and communicates with Android devices via ADB (Android Debug Bridge). It exposes **19 practical tools** to AI assistants (such as Claude, CodeBuddy, etc.), covering the complete Android development and debugging workflow:

```
Screenshot → UI Analysis → Interaction → Logcat → App Management → File Transfer
```

---

## Prerequisites

- Python >= 3.11
- [uv](https://docs.astral.sh/uv/) package manager
- ADB installed and added to PATH (`adb --version` works)
- Android device connected or emulator running (`adb devices` recognizes it)
- **USB Debugging** enabled on the Android device

---

## Installation

```bash
# Clone the project
git clone https://github.com/huarangmeng/AndroidMcpServer
cd AndroidMcpServer

# Install dependencies
uv sync
```

**Dependencies**

| Package | Version | Purpose |
|---|---|---|
| `mcp[cli]` | >= 1.2.0 | MCP framework |
| `Pillow` | >= 10.3.0 | Screenshot processing |

---

## Configuration

### CodeBuddy

Add the following to `~/.codebuddy/mcp.json`:

```json
{
  "mcpServers": {
    "android_mcp": {
      "command": "/Users/<your-username>/.local/bin/uv",
      "args": [
        "run",
        "--project", "/path/to/AndroidMcpServer",
        "python",
        "/path/to/AndroidMcpServer/main.py",
        "--mode", "stdio",
        "--temp-dir", "/tmp/android_mcp"
      ],
      "transportType": "stdio"
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "android_mcp": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/AndroidMcpServer",
        "python",
        "/path/to/AndroidMcpServer/main.py",
        "--mode", "stdio",
        "--temp-dir", "/tmp/android_mcp"
      ]
    }
  }
}
```

### HTTP Mode

```bash
# Start HTTP server
uv run main.py --mode streamable-http --temp-dir /tmp/android_mcp --port 3001

# Service URL: http://localhost:3001/mcp
```

---

## Tools

A total of **19 tools** in 5 categories:

### 📸 Screenshot & UI Analysis

| Tool | Description |
|---|---|
| `get_screenshot` | Capture device screenshot (auto-scaled to 50%) |
| `get_ui_dump` | Get XML UI hierarchy with attribute filtering |

### 🖱️ Interaction

| Tool | Parameters | Description |
|---|---|---|
| `tap_screen` | `x`, `y` | Tap at coordinates |
| `swipe_screen` | `x1`,`y1`,`x2`,`y2`,`duration_ms` | Swipe gesture |
| `long_press` | `x`, `y`, `duration_ms` | Long press |
| `send_text` | `text_to_send` | Send text to focused input (English only) |
| `perform_system_action` | `action` | System keys: BACK / HOME / RECENT_APPS |

### 📱 App Management

| Tool | Parameters | Description |
|---|---|---|
| `launch_app` | `package_name` | Launch app |
| `force_stop_app` | `package_name` | Force stop app |
| `clear_app_data` | `package_name` | Clear app data |
| `install_apk` | `apk_path`, `replace_existing` | Install APK |
| `get_app_list` | `include_system_apps` | List installed apps |
| `grant_permission` | `package_name`, `permission` | Grant runtime permission |

### 🔍 Debugging & Diagnostics

| Tool | Parameters | Description |
|---|---|---|
| `get_logcat_output` | `app_package`, `log_level` | Get last 100 logcat lines |
| `get_device_info` | — | Get device model, OS version, etc. |
| `get_current_activity` | — | Get current foreground Activity |
| `get_memory_info` | `package_name` | View app memory usage |

### 📂 File Operations

| Tool | Parameters | Description |
|---|---|---|
| `pull_file` | `device_path`, `local_path` | Pull file from device |
| `push_file` | `local_path`, `device_path` | Push file to device |

---

## Debugging

Use [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for local debugging:

```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Start with config file
npx @modelcontextprotocol/inspector --config mcp-inspector-config.json --server android-stdio
```

Or start manually:

```bash
# stdio mode
uv run main.py --mode stdio --temp-dir /tmp/android_mcp

# HTTP mode
uv run main.py --mode streamable-http --temp-dir /tmp/android_mcp --port 3001
```

---

## References

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP](https://github.com/jlowin/fastmcp)
- [Android Debug Bridge (ADB)](https://developer.android.com/tools/adb)