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.

中文文档

---

Table of Contents

• Introduction
• Prerequisites
• Installation
• Configuration
• Tools
• Debugging
• References

---

Introduction

This project is built on the 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 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

# 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:

{
  "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:

{
  "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

# 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 for local debugging:

# 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:

# 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
• FastMCP
• Android Debug Bridge (ADB)