# scrcpy-mcp [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/JuanCF/scrcpy-mcp  
**GitHub Stars:** 131  
**npm Downloads (last month):** 1194  
**Views:** 13  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/scrcpy-mcp

## Description
MCP server for Android device control via ADB and scrcpy

## Tools
Capabilities this server exposes over MCP:

- **start_session** — Start a scrcpy session for fast input control and screenshots. When a session is active, tap/swipe/text/screenshot are 10-50x faster. Requires scrcpy-server to be installed.
- **stop_session** — Stop the active scrcpy session. Tools will fall back to ADB commands.
- **version** — Report which scrcpy version is being used by the MCP server. The version always describes the scrcpy-server file the session pushes: it comes from the SCRCPY_SERVER_VERSION environment variable, or from the scrcpy client belonging to the same install as that server, or a built-in default.
- **device_list** — List all connected Android devices with their serial numbers, state, and model
- **device_info** — Get detailed info about a device: model, Android version, screen size, SDK level, battery level
- **screen_on** — Wake the device screen (turn screen on)
- **screen_off** — Turn the device screen off
- **connect_wifi** — Enable WiFi ADB and connect to the device wirelessly. Returns the connection address.
- **disconnect_wifi** — Disconnect from a wireless ADB device
- **rotate_device** — Rotate the device screen (requires active scrcpy session)
- **expand_notifications** — Expand the notification panel (requires active scrcpy session)
- **expand_settings** — Expand the quick settings panel (requires active scrcpy session)
- **collapse_panels** — Collapse all open panels (notification, settings) (requires active scrcpy session)
- **screenshot** — Take a screenshot of the Android device screen. Returns the image as base64.
- **screen_record_start** — Start recording the screen. Recording continues until screen_record_stop is called.
- **screen_record_stop** — Stop screen recording and optionally pull the file to the host.
- **tap** — Tap at the specified screen coordinates
- **swipe** — Perform a swipe gesture from one point to another
- **long_press** — Perform a long press at the specified coordinates
- **drag_drop** — Perform a drag and drop gesture from one point to another. Uses input draganddrop on Android 8.0+ (API 26), falls back to swipe on older versions.
- **input_text** — Type text into the currently focused input field
- **key_event** — Send a key event to the device. Supports keycodes like HOME, BACK, ENTER, VOLUME_UP, etc.
- **scroll** — Scroll at the specified position. dx and dy are scroll amounts (-1 to 1 range approximated for ADB).
- **app_start** — Launch an app on the device. Uses scrcpy START_APP when a session is active for faster launch, falls back to ADB `am start`. Supports force-stop prefix (+) to stop the app before launching.
- **app_stop** — Force-stop an app on the device.
- **app_install** — Install an APK file on the device from the host machine.
- **app_uninstall** — Uninstall an app from the device.
- **app_list** — List installed packages on the device. Optionally filter by name or restrict to system/third-party apps.
- **app_current** — Get the currently foregrounded app package name and activity.
- **clipboard_get** — Get the current clipboard content from the device. Uses scrcpy GET_CLIPBOARD when a session is active (works on Android 10+), falls back to ADB clipboard commands.
- **clipboard_set** — Set the clipboard content on the device. Uses scrcpy SET_CLIPBOARD when a session is active (with optional paste flag), falls back to ADB clipboard commands.
- **ui_dump** — Dump the full UI hierarchy of the current screen as XML. Useful for understanding screen structure before using ui_find_element.
- **ui_find_element** — Find UI elements on screen by text, resource ID, class name, or content description. Returns matching elements with their tap coordinates. At least one search criterion must be provided.
- **shell_exec** — Execute an arbitrary ADB shell command on the device and return the output. Use this for any device operation not covered by other tools.
- **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.
- **start_video_stream** — Start an HTTP MJPEG video stream of the device screen and open a viewer window (ffplay). Starts a scrcpy session automatically if needed.
- **stop_video_stream** — Stop the HTTP MJPEG video stream and close the viewer window for a device.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "scrcpy-mcp": {
    "command": "npx",
    "args": ["-y","scrcpy-mcp"]
  }
}
```

## Documentation

## What scrcpy-mcp MCP server does

The scrcpy-mcp MCP server gives an MCP client control and visibility over connected Android devices. It can list devices, report device details, wake or turn off the screen, rotate the display, manage notification and quick-settings panels, and capture screenshots as images. It also supports touch actions, swipes, long presses, drag-and-drop, scrolling, text entry, and Android key events.

Application tools cover launching, force-stopping, installing, uninstalling, and listing packages. `app_current` reports the foreground package and activity. For UI automation, `ui_dump` returns the device's UI hierarchy as XML, while `ui_find_element` searches by text, resource ID, class name, or content description and returns coordinates that can be tapped.

## How it works

The server communicates with Android through ADB. When `start_session` is used and scrcpy is available, input and screenshots use scrcpy's binary control path. The documented performance is approximately 5–10 ms for input and about 33 ms for screenshots, compared with roughly 500 ms for ADB screenshots. Calling `stop_session` returns supported operations to the ADB path.

The scrcpy-mcp MCP server can start an HTTP MJPEG stream and open an ffplay viewer window. The video tool starts a scrcpy session automatically when necessary. Screen recordings begin on the device and can optionally be pulled to the host when stopped. Session-specific controls include maximum frame size, frame rate, audio capture, keeping the device awake while plugged in, and a temporary screen-off timeout when supported by the installed scrcpy version.

## Setup and configuration

Install Node.js 24 or newer and Android Platform Tools, then enable Developer Options and USB debugging on the Android device. Connect it over USB, accept the device's RSA prompt, and verify that `adb devices` reports state `device` rather than `unauthorized`.

Install or run the server with either `npx scrcpy-mcp` or `npm install -g scrcpy-mcp`. Add that command to the MCP client's server configuration using the client's standard command-based setup. The README provides configurations for Claude Code, OpenCode, Cursor, Claude Desktop, and VS Code with GitHub Copilot.

scrcpy is optional for basic ADB operation but provides the faster session path. ffmpeg is needed for scrcpy video decoding, and ffplay is needed for the viewer window. A nonstandard scrcpy server location can be supplied with `SCRCPY_SERVER_PATH`; `SCRCPY_SERVER_VERSION` is available when automatic version detection fails and must match the installed scrcpy version.

## Limitations and notes

The scrcpy-mcp MCP server requires a reachable Android device and working ADB authorization. Rotation, notification-panel, quick-settings, and panel-collapse tools require an active scrcpy session. Video streaming also requires scrcpy and ffplay. If scrcpy is unavailable or stopped, the applicable tools use slower ADB behavior instead.

The listed screen and input tools operate on coordinates, so callers need current screen dimensions or screenshot context. Screen recordings are created on the device and are only copied to the host when requested during the stop operation. The server's documented setup targets Android devices with USB debugging; wireless use is represented by the separate ADB connection tools in the broader tool reference, but the core setup uses USB.

_Full upstream README: https://allmcps.com/mcp/scrcpy-mcp/readme_