Android MCP Server

Android MCP Server

A Model Context Protocol (MCP) server providing comprehensive Android device control with 22 powerful tools for UI automation, screen capture, and ultra-fast H.264 streaming via Scrcpy.

Features

• 📸 Screenshots: Capture screenshots from Android devices
• 👆 Touch & Gestures: Simulate touch, long press, swipe, and multi-point interactions
• ⌨️ Text Input & Key Events: Direct text input and key event simulation (2 tools)
  • Send key events (HOME, BACK, ENTER, etc.)
  • Input text directly into focused fields
• 🔧 Generic ADB Commands: Execute any ADB command with custom parameters (1 tool)
  • Full flexibility for agents to run custom ADB operations
  • Access to all ADB functionality (logcat, shell commands, package manager, etc.)
• 🎯 UIAutomator: Full UI hierarchy inspection and element interaction (10 tools)
  • Dump complete XML UI hierarchy
  • Find elements by resource ID or text
  • Click, double-click, long-click on elements
  • Set/clear text in input fields
  • Toggle checkboxes
  • Wait for elements to appear
  • Scroll within specific elements
• ⚡ Scrcpy Streaming: Ultra-fast H.264 video streaming (4 tools)
  • Start/stop H.264 video streams (~2s setup, <50ms frame polling)
  • Capture single frames (100-300ms) or latest stream frames (<50ms)
  • Dramatically faster than screenshot capture
• 🚀 App Management: Launch apps and list installed packages
• 🔌 ADB Integration: Direct integration with Android Debug Bridge
• ⚡ Auto-Download: Automatically downloads ADB and Scrcpy from official sources

Prerequisites

• Node.js 18 or higher
• Android device connected via USB with USB debugging enabled, or emulator running

Note: ADB (Android Debug Bridge) and Scrcpy are optional - the server automatically downloads them from official sources on first use if needed.

Quick Start

1. Clone and Build

   git clone https://github.com/jduartedj/android-mcp-server.git
   cd android-mcp-server
   npm install
   npm run build
   

2. Test the Server

   node dist/index.js
   

   The server will start and automatically download ADB/Scrcpy if needed.

3. Add to VS Code (see VS Code Integration below)

Installation

npm install
npm run build

Usage

Running the Server Standalone

node dist/index.js

Configuration

The server supports the following environment variables:

• ADB_PATH: Custom path to ADB executable (default: uses system PATH or auto-downloads)
• DEVICE_SERIAL: Specific device serial number to target (default: first available device)

VS Code Integration

Adding to VS Code GitHub Copilot

To use this MCP server with GitHub Copilot in VS Code:

1. Open VS Code Settings (Ctrl+, or Cmd+,)

2. Search for MCP or navigate to: GitHub Copilot > Chat > MCP Servers

3. Edit the MCP configuration by clicking "Edit in settings.json"

4. Add the Android MCP Server to your configuration:

{
  "github.copilot.chat.mcp.servers": {
    "android-mcp-server": {
      "command": "node",
      "args": ["F:\\android-mcp-server\\dist\\index.js"],
      "env": {
        "ADB_PATH": "",
        "DEVICE_SERIAL": ""
      }
    }
  }
}

Note: Replace F:\\android-mcp-server\\dist\\index.js with the actual absolute path to your dist/index.js file. Use double backslashes on Windows.

5. Alternative: Using npx (if published to npm):

{
  "github.copilot.chat.mcp.servers": {
    "android-mcp-server": {
      "command": "npx",
      "args": ["-y", "android-mcp-server"]
    }
  }
}

6. Reload VS Code or restart the GitHub Copilot extension

Verifying the Integration

After adding the server:

1. Open GitHub Copilot Chat in VS Code
2. Type @workspace and you should see the Android MCP tools available
3. Try asking: "Take a screenshot of my Android device"
4. Copilot will use the appropriate tool to capture the screen

Example Prompts for Copilot

Once integrated, you can ask GitHub Copilot:

• "Take a screenshot of my Android device"
• "Start streaming my device screen for real-time monitoring"
• "Get the latest frame from the stream"
• "Tap at coordinates 500, 1000 on my phone"
• "Swipe up on my Android screen"
• "Press the back button on my device"
• "Send the home key event"
• "Type 'hello world' into the current field"
• "Press enter to submit the form"
• "Get the device battery status using ADB"
• "Read the logcat output for debugging"
• "Clear the app data for com.example.app"
• "List all installed packages"
• "Launch the Chrome app"
• "Find the login button and click it"
• "Fill in the email field with [email protected]"
• "Dump the UI hierarchy of the current screen"
• "Long press on the menu button"
• "Scroll down in the settings list"
• "Toggle the enable notifications checkbox"
• "Wait for the loading indicator to disappear"

All 22 MCP Tools

Basic Tools (5)

1. android_screenshot

Capture a screenshot from the Android device.

Parameters:

• outputPath (optional): Local path to save the screenshot. If not provided, returns base64 encoded image.
• deviceSerial (optional): Target specific device by serial number

Performance: ~1-2 seconds per capture

Example:

{
  "name": "android_screenshot",
  "arguments": {
    "outputPath": "./screenshot.png"
  }
}

2. android_touch

Simulate a touch event at specific screen coordinates. Supports both quick taps and long presses.

Parameters:

• x (required): X coordinate
• y (required): Y coordinate
• duration (optional): Touch duration in milliseconds (default: 100ms for tap, >100ms for long press)
• deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Example - Quick Tap:

{
  "name": "android_touch",
  "arguments": { "x": 500, "y": 1000, "duration": 100 }
}

Example - Long Press:

{
  "name": "android_touch",
  "arguments": { "x": 500, "y": 1000, "duration": 2000 }
}

3. android_swipe

Perform a swipe gesture between two coordinates.

Parameters:

• startX (required): Starting X coordinate
• startY (required): Starting Y coordinate
• endX (required): Ending X coordinate
• endY (required): Ending Y coordinate
• duration (optional): Swipe duration in milliseconds (default: 300)
• deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Example:

{
  "name": "android_swipe",
  "arguments": {
    "startX": 500, "startY": 1500, "endX": 500, "endY": 500, "duration": 300
  }
}

4. android_launch_app

Launch an Android app by package name.

Parameters:

• packageName (required): Package name of the app (e.g., com.example.app, com.google.android.apps.maps)
• deviceSerial (optional): Target specific device by serial number

Performance: ~1-2 seconds

Example:

{
  "name": "android_launch_app",
  "arguments": { "packageName": "com.example.app" }
}

5. android_list_packages

List installed packages on the Android device with optional filtering.

Parameters:

• filter (optional): Search filter for package names (case-insensitive)
• deviceSerial (optional): Target specific device by serial number

Performance: Medium (retrieves full package list)

Example - List All Packages:

{
  "name": "android_list_packages",
  "arguments": {}
}

Example - Filter Packages:

{
  "name": "android_list_packages",
  "arguments": { "filter": "google" }
}

Text Input & Key Event Tools (2)

6. android_input_text

Input text into the currently focused field on the Android device via ADB.

Parameters:

• text (required): Text to input. Spaces are automatically handled.
• deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Use Cases:

• Quick text input without UIAutomator
• Inputting text when element resource ID is unknown
• Simple form filling
• Command-line style text entry

Example:

{
  "name": "android_input_text",
  "arguments": {
    "text": "[email protected]"
  }
}

7. android_send_key_event

Send a key event to the Android device (e.g., HOME, BACK, ENTER).

Parameters:

• keyCode (required): Key event code. Can be key name (e.g., KEYEVENT_HOME, KEYEVENT_BACK) or numeric code (e.g., 3 for HOME, 4 for BACK)
• deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Common Key Codes:

• KEYEVENT_HOME or 3 - Home button
• KEYEVENT_BACK or 4 - Back button
• KEYEVENT_ENTER or 66 - Enter/Return key
• KEYEVENT_DEL or 67 - Delete key
• KEYEVENT_MENU or 82 - Menu button
• KEYEVENT_VOLUME_UP or 24 - Volume up
• KEYEVENT_VOLUME_DOWN or 25 - Volume down
• KEYEVENT_POWER or 26 - Power button

Use Cases:

• Navigation (HOME, BACK)
• Submitting forms (ENTER)
• Controlling device functions (VOLUME, POWER)
• Keyboard shortcuts

Example:

{
  "name": "android_send_key_event",
  "arguments": {
    "keyCode": "KEYEVENT_BACK"
  }
}

Generic ADB Command Tool (1)

8. android_execute_command

Execute a generic ADB command with custom arguments. This powerful tool gives agents full flexibility to run any ADB command with their own parameters.

Parameters:

• args (required): Array of ADB command arguments (e.g., ["shell", "pm", "list", "packages"])
• deviceSerial (optional): Target specific device by serial number

Performance: Varies by command

Returns: Both stdout and stderr from the command execution

Use Cases:

• Execute custom shell commands
• Access logcat for debugging
• Manage packages (install, uninstall, clear data)
• Query device properties
• File operations (push, pull)
• Network operations (port forwarding)
• Any ADB functionality not covered by specific tools

Common Examples:

**

---

README truncated. View full README on GitHub.