home / mcp / scrcpy mcp server

Scrcpy MCP Server

Provides full Android device control and visualization for AI agents via ADB and scrcpy.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "juancf-scrcpy-mcp": {
      "command": "npx",
      "args": [
        "scrcpy-mcp"
      ],
      "env": {
        "ADB_PATH": "adb",
        "FFMPEG_PATH": "ffmpeg",
        "ANDROID_SERIAL": "emulator-5554",
        "SCRCPY_SERVER_PATH": "/usr/local/bin/scrcpy-server",
        "SCRCPY_SERVER_VERSION": "1.28"
      }
    }
  }
}

You can connect AI assistants to an Android device to see the screen, interact via taps and swipes, launch apps, inspect UI elements, transfer files, and run shell commands. This MCP server enables full vision and control over Android devices through ADB and scrcpy, delivering fast interactions and robust capabilities for automation and remote control.

How to use

To use this MCP server, start by launching it through your preferred MCP client. When a session is active, you gain access to rapid input and near-instantaneous screenshots, enabling you to perform tasks such as tapping, swiping, typing, launching apps, and inspecting the UI. You can also pull down notifications, access settings, and navigate the device using specialized tools that map to practical actions. Start a session once to unlock the fast input path, then continue issuing commands to interact with the device.

How to install

Prerequisites you need before installation:

Node.js 18+
ADB (Android Platform Tools)
Android device with USB debugging enabled
Optional: scrcpy and ffmpeg (for best performance)

Install and run the MCP server using one of the following approaches.

# Run directly with npx (no install needed)
npx scrcpy-mcp

# Or install globally
npm install -g scrcpy-mcp

Additional setup notes

Device setup steps you should complete on the Android device: enable Developer Options, enable USB debugging, connect via USB, accept the RSA fingerprint prompt, and verify the device is recognized by ADB.

MCP client configuration (example)

To connect from a client, use the following command pattern in your client configuration. The client will start an MCP server session and route commands through the local MCP instance.

# Example client configuration (Claude Code, OpenCode, Cursor, etc.)
# Start the MCP server via npx
npx scrcpy-mcp

Available tools

start_session

Start a scrcpy session. When active, input and screenshots use the fast path (10-50x faster).

stop_session

Stop the scrcpy session. Tools fall back to ADB.

device_list

List all connected devices with serial, state, and model.

device_info

Get model, Android version, screen size, SDK level, battery.

screen_on

Wake the device screen.

screen_off

Turn the screen off.

rotate_device

Rotate the screen (requires active session).

expand_notifications

Pull down the notification panel (requires active session).

expand_settings

Pull down the quick settings panel (requires active session).

collapse_panels

Collapse notification/settings panels (requires active session).

screenshot

Capture the screen and return it as an image. ~33ms with scrcpy, ~500ms via ADB.

screen_record_start

Start recording the screen to a file on the device.

screen_record_stop

Stop recording and optionally pull the file to the host.

tap

Tap at screen coordinates.

swipe

Swipe from one point to another.

long_press

Long press at coordinates.

drag_drop

Drag from one point to another.

input_text

Type a text string into the focused field.

key_event

Send a key event: HOME, BACK, ENTER, VOLUME_UP, VOLUME_DOWN, POWER, etc.

scroll

Scroll at a position.

app_start

Launch an app by package name. Prefix with + to force-stop before launch.

app_stop

Force-stop an app.

app_install

Install an APK from the host machine.

app_uninstall

Uninstall an app.

app_list

List installed packages, optionally filter by name or system/third-party.

app_current

Get the current foreground app and activity.

ui_dump

Dump the full UI hierarchy as XML.

ui_find_element

Find elements by text, resource ID, class name, or content description. Returns tap coordinates.

shell_exec

Execute an arbitrary ADB shell command and return the output.

file_push

Push a file from the host machine to the device.

file_pull

Pull a file from the device to the host machine.

file_list

List directory contents on the device.

clipboard_get

Get clipboard content. Uses scrcpy to bypass Android 10+ restrictions.

clipboard_set

Set clipboard content. Pass paste: true to also paste immediately.