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

Clone and Build
git clone https://github.com/jduartedj/android-mcp-server.git cd android-mcp-server npm install npm run build
Test the Server
node dist/index.js
The server will start and automatically download ADB/Scrcpy if needed.
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:

Open VS Code Settings (Ctrl+, or Cmd+,)
Search for MCP or navigate to: GitHub Copilot > Chat > MCP Servers
Edit the MCP configuration by clicking "Edit in settings.json"
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.

Alternative: Using npx (if published to npm):

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

Reload VS Code or restart the GitHub Copilot extension

Verifying the Integration

After adding the server:

Open GitHub Copilot Chat in VS Code
Type @workspace and you should see the Android MCP tools available
Try asking: "Take a screenshot of my Android device"
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 user@example.com"
"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": "user@example.com" } }

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:

List all packages:

{ "name": "android_execute_command", "arguments": { "args": ["shell", "pm", "list", "packages"] } }

Get device properties:

{ "name": "android_execute_command", "arguments": { "args": ["shell", "getprop", "ro.build.version.release"] } }

Read logcat:

{ "name": "android_execute_command", "arguments": { "args": ["logcat", "-d", "-s", "MyTag:V"] } }

Clear app data:

{ "name": "android_execute_command", "arguments": { "args": ["shell", "pm", "clear", "com.example.app"] } }

Get battery info:

{ "name": "android_execute_command", "arguments": { "args": ["shell", "dumpsys", "battery"] } }

Push file to device:

{ "name": "android_execute_command", "arguments": { "args": ["push", "/local/path/file.txt", "/sdcard/file.txt"] } }

Install APK:

{ "name": "android_execute_command", "arguments": { "args": ["install", "-r", "/path/to/app.apk"] } }

Port forwarding:

{ "name": "android_execute_command", "arguments": { "args": ["forward", "tcp:8080", "tcp:8080"] } }

UIAutomator Tools (10)

9. `android_uiautomator_dump`

Dump the complete UI hierarchy of the current screen as XML for inspection and element identification.

Parameters:

deviceSerial (optional): Target specific device by serial number

Returns: Complete XML UI hierarchy that can be parsed to find element resource IDs and attributes.

Performance: ~500-800ms

Use Cases:

Inspecting app UI structure
Finding element resource IDs for automation
Understanding view hierarchies

Example:

{ "name": "android_uiautomator_dump", "arguments": {} }

10. `android_uiautomator_find`

Find UI elements by resource ID or text content using UIAutomator.

Parameters:

resourceId (optional): Resource ID to search for (e.g., com.example.app:id/button_submit)
text (optional): Text content to search for
deviceSerial (optional): Target specific device by serial number

Performance: Fast

Example - Find by Resource ID:

{ "name": "android_uiautomator_find", "arguments": { "resourceId": "com.example.app:id/email_input" } }

Example - Find by Text:

{ "name": "android_uiautomator_find", "arguments": { "text": "Submit" } }

11. `android_uiautomator_click`

Click on a UI element by resource ID.

Parameters:

resourceId (required): Resource ID of the element to click
deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Example:

{ "name": "android_uiautomator_click", "arguments": { "resourceId": "com.example.app:id/button_submit" } }

12. `android_uiautomator_double_click`

Perform a double-click on a UI element by resource ID.

Parameters:

resourceId (required): Resource ID of the element
deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Example:

{ "name": "android_uiautomator_double_click", "arguments": { "resourceId": "com.example.app:id/text_field" } }

13. `android_uiautomator_long_click`

Perform a long-click on a UI element by resource ID.

Parameters:

resourceId (required): Resource ID of the element
deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Example:

{ "name": "android_uiautomator_long_click", "arguments": { "resourceId": "com.example.app:id/menu_item" } }

14. `android_uiautomator_set_text`

Set text on a UI element by resource ID. Automatically clears existing text first.

Parameters:

resourceId (required): Resource ID of the element
text (required): Text to set
deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Example:

{ "name": "android_uiautomator_set_text", "arguments": { "resourceId": "com.example.app:id/email_input", "text": "user@example.com" } }

15. `android_uiautomator_clear_text`

Clear text from a UI element by resource ID.

Parameters:

resourceId (required): Resource ID of the element
deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Example:

{ "name": "android_uiautomator_clear_text", "arguments": { "resourceId": "com.example.app:id/search_input" } }

16. `android_uiautomator_toggle_checkbox`

Toggle a checkbox element by resource ID.

Parameters:

resourceId (required): Resource ID of the checkbox
deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Example:

{ "name": "android_uiautomator_toggle_checkbox", "arguments": { "resourceId": "com.example.app:id/agree_checkbox" } }

17. `android_uiautomator_wait`

Wait for a UI element to appear by resource ID with timeout support.

Parameters:

resourceId (required): Resource ID to wait for
timeoutMs (optional): Maximum wait time in milliseconds (default: 5000)
deviceSerial (optional): Target specific device by serial number

Performance: Configurable (up to timeout)

Example:

{ "name": "android_uiautomator_wait", "arguments": { "resourceId": "com.example.app:id/loading_indicator", "timeoutMs": 10000 } }

18. `android_uiautomator_scroll_in_element`

Scroll within a specific scrollable UI element.

Parameters:

resourceId (required): Resource ID of the scrollable element
direction (required): Direction to scroll (up, down, left, right)
distance (optional): Distance to scroll in pixels (default: 500)
deviceSerial (optional): Target specific device by serial number

Performance: Immediate

Example:

{ "name": "android_uiautomator_scroll_in_element", "arguments": { "resourceId": "com.example.app:id/list_view", "direction": "down", "distance": 500 } }

Scrcpy Streaming Tools (4)

Scrcpy streaming provides ultra-fast frame capture using H.264 video encoding, perfect for real-time monitoring, rapid screenshot sequences, or continuous frame polling.

19. `android_start_scrcpy_stream`

Initialize an H.264 video stream from the Android device using Scrcpy.

Parameters:

deviceSerial (optional): Target specific device by serial number
bitrate (optional): Video bitrate in Mbps (default: 4)
fps (optional): Frames per second (default: 60)

Performance: ~2 seconds setup, <50ms per frame polling afterward

Advantages:

Ultra-fast frame capture (<50ms vs 1-2s for screenshot)
Continuous streaming with pre-buffered frames
Ideal for real-time monitoring
H.264 compression reduces bandwidth

Example:

{ "name": "android_start_scrcpy_stream", "arguments": { "bitrate": 4, "fps": 30 } }

20. `android_get_latest_frame`

Poll the latest frame from an active Scrcpy stream.

Parameters:

deviceSerial (optional): Target specific device by serial number
outputPath (optional): Save frame to file, otherwise returns base64

Performance: <50ms per frame (due to pre-buffered streaming)

Use Cases:

Real-time monitoring
Rapid screenshot sequences
Continuous frame polling
Streaming visualization

Example:

{ "name": "android_get_latest_frame", "arguments": { "outputPath": "./current_frame.png" } }

21. `android_stop_scrcpy_stream`

Stop an active Scrcpy H.264 stream.

Parameters:

deviceSerial (optional): Target specific device by serial number

Example:

{ "name": "android_stop_scrcpy_stream", "arguments": {} }

22. `android_capture_frame_scrcpy`

Capture a single frame using Scrcpy without starting a persistent stream.

Parameters:

deviceSerial (optional): Target specific device by serial number
outputPath (optional): Save frame to file, otherwise returns base64
bitrate (optional): Video bitrate in Mbps (default: 4)

Performance: 100-300ms (faster than screenshot, slower than streaming)

Use Cases:

One-off frame captures
When streaming overhead isn't justified
Single frame comparison
Lightweight capture operations

Example:

{ "name": "android_capture_frame_scrcpy", "arguments": { "outputPath": "./single_frame.png" } }

Performance Comparison

Tool	Purpose	Speed	Best For
`android_screenshot`	Basic capture	1-2s	Simple screenshots, initial inspection
`android_capture_frame_scrcpy`	Single Scrcpy frame	100-300ms	Faster one-off captures than screenshot
`android_start_scrcpy_stream`	Initialize stream	~2s setup	Real-time monitoring workflows
`android_get_latest_frame`	Poll stream	<50ms	Rapid frame sequences, real-time apps
`android_touch`	Tap/long press	Immediate	UI interaction
`android_swipe`	Swipe gesture	Immediate	Navigation, scrolling
`android_input_text`	Direct text input	Immediate	Quick text entry via ADB
`android_send_key_event`	Key events	Immediate	Navigation (HOME, BACK, ENTER)
`android_execute_command`	Generic ADB	Varies	Custom ADB operations, full flexibility
`android_uiautomator_dump`	UI inspection	500-800ms	Element discovery
`android_uiautomator_find`	Element search	Fast	Located specific elements
`android_uiautomator_*`	Element interaction	Immediate	Form filling, UI automation

Common Use Cases

1. Automated Testing

1. Dump UI hierarchy to find element IDs 2. Click buttons and input text using resource IDs 3. Use streaming to verify visual changes in real-time 4. Scroll and navigate through the app

2. Real-Time Monitoring

1. Start Scrcpy stream (one-time ~2s setup) 2. Poll latest frames continuously (<50ms each) 3. Process frames for visual analysis 4. Stop stream when done

3. Rapid Frame Capture Sequence

1. Start Scrcpy stream 2. Get latest frame multiple times (much faster than screenshot) 3. Process frame sequence for animation/comparison 4. Stop stream

4. Form Filling (WebView or Native)

1. Find form fields by resource ID or text 2. Clear existing text 3. Set new text values 4. Toggle checkboxes and radio buttons 5. Click submit button

5. Multi-Device Automation

Use deviceSerial parameter to target specific devices:

1. List connected devices via ADB 2. Specify device serial for each tool call 3. Automate workflows on multiple devices in parallel 4. Useful for device farms and testing labs

6. App Discovery

1. List all packages (potentially 100+) 2. Filter packages by name (e.g., "google", "com.example") 3. Launch apps by package name 4. Perfect for discovering available apps on the device

ADB & Scrcpy Setup

Automatic Installation

The server automatically downloads and installs from official sources:

ADB: From Android Platform Tools
Scrcpy: From official releases

Downloaded tools stored in ~/.android-mcp-server/platform-tools/

Manual Installation (Optional)

Windows:

choco install adb choco install scrcpy

macOS:

brew install android-platform-tools brew install scrcpy

Linux (Ubuntu/Debian):

sudo apt-get install android-tools-adb scrcpy

Enabling USB Debugging on Android

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 accept the debugging prompt

Verify Connection

adb devices

You should see your device listed.

Troubleshooting

Issue	Solution
"No Android devices found"	Ensure device is connected via USB and USB debugging is enabled. Run `adb devices` to verify.
UIAutomator element not found	Use `android_uiautomator_dump` to inspect the XML and verify the resource ID exists.
Scrcpy stream won't start	Ensure Scrcpy is installed or allow auto-download to complete. Check device is connected.
"ADB not found" error	Run the server once to auto-download ADB, or manually install platform-tools.
Touch coordinates not working	Verify coordinates are within screen bounds. Use screenshots to determine correct coordinates.
App launch fails	Verify package name is correct using `android_list_packages` . Try filtering if unsure.
Streaming frames are slow	Reduce bitrate/fps or use single `android_capture_frame_scrcpy` for one-off captures.

Advanced Patterns

Real-Time Visual Monitoring

1. android_start_scrcpy_stream (2s setup) 2. Loop: android_get_latest_frame (<50ms each) 3. Process frames for ML/analysis 4. android_stop_scrcpy_stream when done

Stress Testing with Rapid Frames

1. Start stream 2. Perform action on device 3. Capture 10+ frames in rapid succession (<50ms each) 4. Compare frame changes for regression detection

Multi-Step Form Automation

1. android_uiautomator_dump (find all fields) 2. For each field: - android_uiautomator_find (locate) - android_uiautomator_set_text (fill) 3. android_uiautomator_click (submit) 4. android_uiautomator_wait (result screen) 5. android_screenshot (verify)

Device Farm Parallel Testing

1. Get device list 2. For each device: - Specify deviceSerial in all tool calls - Run automation sequence - Compare results across devices

Architecture

The server uses the Model Context Protocol to expose Android device control:

ADB Wrapper (src/adb-wrapper.ts): Device communication, auto-downloads ADB
Scrcpy Integration (src/adb-wrapper.ts): H.264 streaming, frame polling
UIAutomator Methods (src/adb-wrapper.ts): Full XML dumping, element interaction
Tool Handlers (src/handlers.ts): All 19 tool operations
MCP Server (src/index.ts): Exposes all tools via Model Context Protocol

Supported Android Versions

Android 5.0+ (API Level 21+)
Scrcpy streaming: Android 5.0+ via ADB, optimal on 7.0+

Development

# Install dependencies npm install # Build npm run build # Watch mode (if supported) npm run watch

Adding New Tools

To add a new tool:

Implement method in src/adb-wrapper.ts
Implement handler in src/handlers.ts
Register tool in src/index.ts with name, description, and schema
Build and test with the server running

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Android MCP Server

Features

Prerequisites

Quick Start

Installation

Usage

Running the Server Standalone

Configuration

VS Code Integration

Adding to VS Code GitHub Copilot

Verifying the Integration

Example Prompts for Copilot

All 22 MCP Tools

Basic Tools (5)

1. android_screenshot

2. android_touch

3. android_swipe

4. android_launch_app

5. android_list_packages

Text Input & Key Event Tools (2)

6. android_input_text

7. android_send_key_event

Generic ADB Command Tool (1)

8. android_execute_command

UIAutomator Tools (10)

9. android_uiautomator_dump

10. android_uiautomator_find

11. android_uiautomator_click

12. android_uiautomator_double_click

13. android_uiautomator_long_click

14. android_uiautomator_set_text

15. android_uiautomator_clear_text

16. android_uiautomator_toggle_checkbox

17. android_uiautomator_wait

18. android_uiautomator_scroll_in_element

Scrcpy Streaming Tools (4)

19. android_start_scrcpy_stream

20. android_get_latest_frame

21. android_stop_scrcpy_stream

22. android_capture_frame_scrcpy

Performance Comparison

Common Use Cases

1. Automated Testing

2. Real-Time Monitoring

3. Rapid Frame Capture Sequence

4. Form Filling (WebView or Native)

5. Multi-Device Automation

6. App Discovery

ADB & Scrcpy Setup

Automatic Installation

Manual Installation (Optional)

Enabling USB Debugging on Android

Verify Connection

Troubleshooting

Advanced Patterns

Real-Time Visual Monitoring

Stress Testing with Rapid Frames

Multi-Step Form Automation

Device Farm Parallel Testing

Architecture

Supported Android Versions

Development

Adding New Tools

License

Contributing

Related Resources

Tools

New MCP Servers

MCP directory API

1. `android_screenshot`

2. `android_touch`

3. `android_swipe`

4. `android_launch_app`

5. `android_list_packages`

6. `android_input_text`

7. `android_send_key_event`

8. `android_execute_command`

9. `android_uiautomator_dump`

10. `android_uiautomator_find`

11. `android_uiautomator_click`

12. `android_uiautomator_double_click`

13. `android_uiautomator_long_click`

14. `android_uiautomator_set_text`

15. `android_uiautomator_clear_text`

16. `android_uiautomator_toggle_checkbox`

17. `android_uiautomator_wait`

18. `android_uiautomator_scroll_in_element`

19. `android_start_scrcpy_stream`

20. `android_get_latest_frame`

21. `android_stop_scrcpy_stream`

22. `android_capture_frame_scrcpy`