Android MCP Server

A powerful MCP (Model Context Protocol) server that provides comprehensive Android device automation capabilities through ADB (Android Debug Bridge). This server enables AI agents and automation tools to interact with Android devices for testing, automation, and device control tasks.

https://github.com/user-attachments/assets/68f3df22-fcf1-49af-8715-fcfa05496c90

🚀 Features

Device Management

• Multi-device support: Connect and manage multiple Android devices simultaneously
• Auto-discovery: Automatic device detection and selection
• Health monitoring: Real-time device status and connectivity checks
• Device information: Complete device specifications and capabilities

UI Automation

• Layout inspection: Extract complete UI hierarchy with element details
• Smart element finding: Search UI elements by text, resource ID, content description, or class
• Gesture control: Tap, swipe, and multi-touch gesture support
• Text input: Send text and key events (back, home, menu, etc.)

Media Capture

• Screenshots: High-quality screen capture with customizable options
• Screen recording: MP4 video recording with quality controls
• Batch operations: Multiple concurrent recording sessions

Advanced Monitoring

• Live log monitoring: Real-time logcat streaming with filtering
• Multi-session support: Concurrent log monitoring with different filters
• Export capabilities: Save logs and media to local filesystem

📋 Prerequisites

Required Software

• Python 3.11+: Runtime environment
• Android SDK Platform Tools: For ADB functionality
• USB Debugging enabled: On target Android devices

ADB Setup

1. Install Android SDK Platform Tools:

   # macOS (via Homebrew)
   brew install android-platform-tools
   
   # Ubuntu/Debian
   sudo apt install android-tools-adb
   
   # Windows
   # Download from: https://developer.android.com/tools/releases/platform-tools
   

2. Verify ADB installation:

   adb version
   # Should output: Android Debug Bridge version x.x.x
   

3. Enable USB Debugging on Android device:

   • Go to Settings → About Phone
   • Tap "Build number" 7 times to enable Developer Options
   • Go to Settings → Developer Options
   • Enable "USB Debugging"
   • Connect device via USB and authorize when prompted

⚙️ Installation

Using uv (Recommended)

git clone <repository-url>
cd android-mcp-server
uv sync

Using pip

git clone <repository-url>
cd android-mcp-server
pip install -e .

Verify Installation

# Check if devices are detected
adb devices

# Test server startup
python -m src.server

🚀 Quick Start

Basic Usage Example

import asyncio
from mcp import ClientSession

async def demo_automation():
    # Connect to MCP server
    session = ClientSession()

    # Get connected devices
    devices = await session.call_tool("get_devices")
    print(f"Found {devices['count']} devices")

    # Take a screenshot
    screenshot = await session.call_tool("take_screenshot", {
        "filename": "demo_screenshot.png"
    })

    # Find and tap a button
    elements = await session.call_tool("find_elements", {
        "text": "Settings",
        "clickable_only": True
    })

    if elements["count"] > 0:
        result = await session.call_tool("tap_element", {
            "text": "Settings"
        })
        print("Tapped Settings button")

# Run the demo
asyncio.run(demo_automation())

Command Line Usage

# Start the MCP server
python -m src.server

# Or using the installed script
android-mcp-server

🛠️ Available Tools

Device Management

• get_devices(): List all connected Android devices
• select_device(device_id?): Select specific device or auto-select first available
• get_device_info(): Get detailed device information and screen specifications

UI Interaction

• get_ui_layout(compressed?, include_invisible?): Extract complete UI hierarchy
• find_elements(...): Find UI elements by text, resource ID, content description, or class
• tap_screen(x, y): Tap at specific screen coordinates
• tap_element(text?, resource_id?, content_desc?, index?): Find and tap UI element
• swipe_screen(start_x, start_y, end_x, end_y, duration_ms?): Swipe between coordinates
• swipe_direction(direction, distance?, duration_ms?): Swipe in direction (up/down/left/right)
• input_text(text, clear_existing?): Input text into focused field
• press_key(keycode): Press device keys (BACK, HOME, ENTER, etc.)

Media Capture

• take_screenshot(filename?, pull_to_local?): Capture device screenshot
• start_screen_recording(...): Start screen recording with quality options
• stop_screen_recording(recording_id?, pull_to_local?): Stop recording session
• list_active_recordings(): List all active recording sessions

Log Monitoring

• get_logcat(tag_filter?, priority?, max_lines?, clear_first?): Get device logs
• start_log_monitoring(tag_filter?, priority?, output_file?): Start continuous log monitoring
• stop_log_monitoring(monitor_id?): Stop log monitoring session
• list_active_monitors(): List active monitoring sessions

🔌 MCP Server Installation

Add to Claude Desktop (Recommended)

1. Locate your Claude Desktop configuration file:

   # macOS
   ~/Library/Application Support/Claude/claude_desktop_config.json
   
   # Windows
   %APPDATA%/Claude/claude_desktop_config.json
   

2. Add the Android MCP Server:

   {
     "mcpServers": {
       "android-mcp-server": {
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/android-mcp-server",
           "run",
           "android-mcp-server"
         ]
       }
     }
   }
   

3. Restart Claude Desktop to activate the server.

Alternative Installation Methods

Using Python directly

{
  "mcpServers": {
    "android-mcp-server": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/android-mcp-server"
    }
  }
}

Using pip installed package

pip install -e /path/to/android-mcp-server

{
  "mcpServers": {
    "android-mcp-server": {
      "command": "android-mcp-server"
    }
  }
}

🤖 Usage Examples for AI Agents

Basic Device Interaction

"Take a screenshot of the current Android device screen and then find all buttons containing the word 'Settings'"

"Connect to the Android device, open the Settings app by tapping on it, then take another screenshot"

"Swipe down from the top of the screen to open the notification panel, then capture what's shown"

App Testing and Automation

"Launch the Calculator app, perform the calculation 25 + 37, and verify the result is 62"

"Test the login flow: find the username field, enter 'testuser', find the password field, enter 'password123', then tap the login button"

"Navigate through the app's main menu by tapping each menu item and taking screenshots of each page"

UI Analysis and Debugging

"Extract the complete UI layout of the current screen and identify all clickable elements"

"Find all text input fields on this screen and tell me which ones are currently focused"

"Look for any accessibility issues by checking if buttons have proper content descriptions"

Log Monitoring and Debugging

"Start monitoring logs for the 'MyApp' package and show me any errors that occur in the next 2 minutes"

"Get the last 50 lines of system logs with priority level Warning or higher"

"Monitor network-related logs while I perform the next action, then show me what was logged"

Performance Testing

"Record a 30-second video of the app launch sequence, then analyze the UI responsiveness"

"Take screenshots before and after each major user action to document the user flow"

"Monitor memory usage logs while navigating through different screens of the app"

Multi-Device Testing

"List all connected Android devices and select the one with the largest screen resolution"

"Switch to device ID 'emulator-5554' and repeat the previous test sequence"

"Compare the same UI element across different devices by taking screenshots on each"

💡 Tips for AI Agents

Efficient Element Finding

• Always use find_elements before tap_element to verify elements exist
• Use exact_match: false for partial text matching when element text might vary
• Combine multiple search criteria (text + clickable_only) for more precise targeting

Context-Aware Log Monitoring

• Limit max_lines to 20-200 to avoid overwhelming the AI context window
• Use specific tag_filter to focus on relevant app components
• Set appropriate priority level (I/W/E) based on the type of information needed

Screenshot-Driven Workflows

• Take screenshots before and after actions for verification
• Use descriptive filenames that indicate the test step or app state
• Screenshots are automatically saved to ./assets/ for easy access

Robust Automation Patterns

• Check device connection with get_device_info before starting automation
• Use get_ui_layout when element finding fails to understand the current screen structure
• Implement retry logic for intermittent UI state issues

🏗️ Architecture

The server is built with a modular architecture:

• ADBManager: Core ADB communication and device management
• UILayoutExtractor: UI hierarchy parsing and element extraction
• ScreenInteractor: Touch and gesture handling
• MediaCapture: Screenshot and recording functionality
• LogMonitor: Real-time log monitoring and filtering
• FastMCP: MCP protocol implementation and tool registration

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Development Setup

git clone <repository-url>
cd android-mcp-server
uv sync --dev

Running Tests

# Install test dependencies
pip install -e ".[test,dev]"

# Run full test suite with coverage
python -m pytest tests/ --cov=src --cov-fail-under=80

# Run specific test categories
python -m pytest tests/ -m "unit"           # Unit tests only
python -m pytest tests/ -m "integration"    # Integration tests
python -m pytest tests/ -m "not slow"       # Skip slow tests

# Run code quality checks
make code-quality  # or run individual tools:
flake8 src
pydocstyle src --convention=google

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• MCP Specification
• Android Debug Bridge (ADB)
• uiautomator