# io.github.JuanCF/scrcpy-mcp (npm · scrcpy-mcp)

MCP server for Android device control via ADB and scrcpy

- Trust score: 80/100 (high trust)
- Change this week: +34
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `scrcpy-mcp`: 80/100 (this document), [markdown](https://verifymcp.io/servers/juancf-scrcpy-mcp/scrcpy-mcp.md), [page](https://verifymcp.io/servers/juancf-scrcpy-mcp/scrcpy-mcp)

## Channel facts

- Registry: `npm`
- Package: `scrcpy-mcp`
- Version: `0.4.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (111 of 115), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (111 of 115), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to JuanCF/scrcpy-mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 28 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 79/100
  - AI-judged instruction clarity (excellent).
  - Tool/resource definitions use about 2179 tokens (~55/item across 39 items; 39 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add juancf-scrcpy-mcp -- npx -y scrcpy-mcp
```

### Codex

```bash
codex mcp add juancf-scrcpy-mcp -- npx -y scrcpy-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "juancf-scrcpy-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "scrcpy-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add juancf-scrcpy-mcp --command npx --arg -y --arg scrcpy-mcp
```

### Hermes

```yaml
mcp_servers:
  juancf-scrcpy-mcp:
    command: "npx"
    args: ["-y", "scrcpy-mcp"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 80, +4)

- [functional improvement] Stability: unverified → 0.27

### 2026-08-02 (score 76, +55)

- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [security improvement] Provenance: unverified → pass
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [security] The attested source repository moved: JuanCF/scrcpy-mcp
- [functional regression] Security disclosure: fail → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional] First check of Schema quality: unverified
- [functional] Licence: MIT

### 2026-08-01 (score 21, −7)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 28, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-27 (score 46)

First indexed and scored.

## MCP tools (39)

### `start_session` (~93 tokens)

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.

Input parameters:

- `maxFps` (integer): Max frames per second (default 30)
- `maxSize` (integer): Max screen dimension in pixels (default 1024)
- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable status message
- `screenSize` (object): Native display resolution — tap/swipe use these native coordinates, matching ui_dump / ui_find_element bounds directly (no scaling)
- `serial` (string): Resolved device serial
- `status` (string): Session status (e.g. 'connected')
- `videoAvailable` (boolean): Whether the scrcpy video stream is up. When false, the session still works for input/clipboard but screenshots fall back to adb screencap.

### `stop_session` (~34 tokens)

Stop the active scrcpy session. Tools will fall back to ADB commands.

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable status message
- `success` (boolean): Whether the session was stopped

### `version` (~47 tokens)

Report which scrcpy version is being used by the MCP server. The version is detected from the SCRCPY_SERVER_VERSION environment variable, the scrcpy --version binary, or a built-in default.

Output parameters:

- `source` (string): Where the version was resolved from: 'env' (SCRCPY_SERVER_VERSION env var), 'binary' (scrcpy --version), or 'default' (built-in constant)
- `version` (string): Scrcpy version string (e.g. '4.0', '2.7')

### `device_list` (~23 tokens)

List all connected Android devices with their serial numbers, state, and model

Output parameters:

- `count` (integer): Number of connected devices
- `devices` (array): Connected devices

### `device_info` (~48 tokens)

Get detailed info about a device: model, Android version, screen size, SDK level, battery level

Input parameters:

- `serial` (string): Device serial number. If omitted, uses the only connected device.

Output parameters:

- `androidVersion`: Android release version
- `batteryLevel`: Battery level percentage
- `brand`: Device brand
- `manufacturer`: Device manufacturer
- `model`: Device model
- `screenHeight` (integer): Screen height in pixels
- `screenWidth` (integer): Screen width in pixels
- `sdkLevel`: Android SDK API level
- `serial` (string): Resolved device serial

### `screen_on` (~27 tokens)

Wake the device screen (turn screen on)

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable description of the result
- `success` (boolean): Whether the action succeeded

### `screen_off` (~24 tokens)

Turn the device screen off

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable description of the result
- `success` (boolean): Whether the action succeeded

### `connect_wifi` (~55 tokens)

Enable WiFi ADB and connect to the device wirelessly. Returns the connection address.

Input parameters:

- `port` (integer): TCP port for ADB connection (default: 5555)
- `serial` (string): Device serial number

Output parameters:

- `address` (string): The host:port the device was connected on
- `message` (string): Human-readable description of the result
- `success` (boolean): Whether the wireless connection was established

### `disconnect_wifi` (~40 tokens)

Disconnect from a wireless ADB device

Input parameters:

- `address` (string, required): Device address (e.g., 192.168.1.100:5555)

Output parameters:

- `message` (string): Human-readable description of the result
- `success` (boolean): Whether the action succeeded

### `rotate_device` (~29 tokens)

Rotate the device screen (requires active scrcpy session)

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable description of the result
- `success` (boolean): Whether the action succeeded

### `expand_notifications` (~29 tokens)

Expand the notification panel (requires active scrcpy session)

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable description of the result
- `success` (boolean): Whether the action succeeded

### `expand_settings` (~30 tokens)

Expand the quick settings panel (requires active scrcpy session)

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable description of the result
- `success` (boolean): Whether the action succeeded

### `collapse_panels` (~35 tokens)

Collapse all open panels (notification, settings) (requires active scrcpy session)

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable description of the result
- `success` (boolean): Whether the action succeeded

### `screenshot` (~33 tokens)

Take a screenshot of the Android device screen. Returns the image as base64.

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `encoding` (string): Encoding of the image data in the content block
- `mimeType` (string): MIME type of the returned image
- `source` (string): Capture path used (scrcpy frame or adb screencap)

### `screen_record_start` (~68 tokens)

Start recording the screen. Recording continues until screen_record_stop is called.

Input parameters:

- `duration` (number): Max recording duration in seconds (optional, device limit usually 180s)
- `remotePath` (string): Path on device to save recording
- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable status message
- `remotePath` (string): Path on the device where the recording is saved
- `success` (boolean): Whether recording was started

### `screen_record_stop` (~68 tokens)

Stop screen recording and optionally pull the file to the host.

Input parameters:

- `localPath` (string): Local path to save recording (only if pullToHost is true)
- `pullToHost` (boolean): Pull the recording to the host machine
- `serial` (string): Device serial number

Output parameters:

- `localPath` (string): Host path the recording was pulled to, if requested
- `message` (string): Human-readable status message
- `success` (boolean): Whether recording was stopped

### `tap` (~42 tokens)

Tap at the specified screen coordinates

Input parameters:

- `serial` (string): Device serial number
- `x` (integer, required): X coordinate
- `y` (integer, required): Y coordinate

Output parameters:

- `message` (string): Human-readable description of the action performed
- `success` (boolean): Whether the input action was dispatched to the device

### `swipe` (~81 tokens)

Perform a swipe gesture from one point to another

Input parameters:

- `duration` (integer): Duration in milliseconds
- `serial` (string): Device serial number
- `x1` (integer, required): Start X coordinate
- `x2` (integer, required): End X coordinate
- `y1` (integer, required): Start Y coordinate
- `y2` (integer, required): End Y coordinate

Output parameters:

- `message` (string): Human-readable description of the action performed
- `success` (boolean): Whether the input action was dispatched to the device

### `long_press` (~55 tokens)

Perform a long press at the specified coordinates

Input parameters:

- `duration` (integer): Duration in milliseconds
- `serial` (string): Device serial number
- `x` (integer, required): X coordinate
- `y` (integer, required): Y coordinate

Output parameters:

- `message` (string): Human-readable description of the action performed
- `success` (boolean): Whether the input action was dispatched to the device

### `drag_drop` (~109 tokens)

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 parameters:

- `duration` (integer): Duration in milliseconds
- `endX` (integer, required): End X coordinate
- `endY` (integer, required): End Y coordinate
- `serial` (string): Device serial number
- `startX` (integer, required): Start X coordinate
- `startY` (integer, required): Start Y coordinate

Output parameters:

- `message` (string): Human-readable description of the action performed
- `success` (boolean): Whether the input action was dispatched to the device

### `input_text` (~37 tokens)

Type text into the currently focused input field

Input parameters:

- `serial` (string): Device serial number
- `text` (string, required): Text to type

Output parameters:

- `message` (string): Human-readable description of the action performed
- `success` (boolean): Whether the input action was dispatched to the device

### `key_event` (~64 tokens)

Send a key event to the device. Supports keycodes like HOME, BACK, ENTER, VOLUME_UP, etc.

Input parameters:

- `keycode` (required): Keycode name (e.g., 'HOME', 'BACK') or numeric value
- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable description of the action performed
- `success` (boolean): Whether the input action was dispatched to the device

### `scroll` (~101 tokens)

Scroll at the specified position. dx and dy are scroll amounts (-1 to 1 range approximated for ADB).

Input parameters:

- `dx` (number, required): Horizontal scroll amount (negative=left, positive=right)
- `dy` (number, required): Vertical scroll amount (negative=up, positive=down)
- `serial` (string): Device serial number
- `x` (integer, required): X coordinate to scroll at
- `y` (integer, required): Y coordinate to scroll at

Output parameters:

- `message` (string): Human-readable description of the action performed
- `success` (boolean): Whether the input action was dispatched to the device

### `app_start` (~99 tokens)

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.

Input parameters:

- `packageName` (string, required): Package name to launch (e.g., 'com.example.app'). Prefix with '+' to force-stop the app first (e.g., '+com.example.app')
- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable description of the result
- `source` (string): Mechanism used to launch the app (scrcpy or adb)
- `success` (boolean): Whether the app was launched

### `app_stop` (~47 tokens)

Force-stop an app on the device.

Input parameters:

- `packageName` (string, required): Package name to force-stop (e.g., 'com.example.app')
- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable description of the result
- `success` (boolean): Whether the app was force-stopped

### `app_install` (~48 tokens)

Install an APK file on the device from the host machine.

Input parameters:

- `apkPath` (string, required): Absolute path to the APK file on the host machine
- `serial` (string): Device serial number

Output parameters:

- `message` (string): Install result or error output from adb
- `success` (boolean): Whether the APK installed successfully

### `app_uninstall` (~47 tokens)

Uninstall an app from the device.

Input parameters:

- `packageName` (string, required): Package name to uninstall (e.g., 'com.example.app')
- `serial` (string): Device serial number

Output parameters:

- `message` (string): Uninstall result or error output from adb
- `success` (boolean): Whether the app was uninstalled

### `app_list` (~79 tokens)

List installed packages on the device. Optionally filter by name or restrict to system/third-party apps.

Input parameters:

- `filter` (string): Filter packages by name (partial match, case-insensitive)
- `serial` (string): Device serial number
- `system` (boolean): true = system apps only, false = third-party only, omit = all

Output parameters:

- `count` (integer): Number of packages returned
- `packages` (array): Installed package names

### `app_current` (~29 tokens)

Get the currently foregrounded app package name and activity.

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `activity`: Foreground activity name, if resolvable
- `packageName` (string): Package name of the foreground app

### `clipboard_get` (~55 tokens)

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.

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `content` (string): Current clipboard text on the device
- `source` (string): Mechanism used to read the clipboard (scrcpy or adb)

### `clipboard_set` (~80 tokens)

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.

Input parameters:

- `paste` (boolean): Also simulate paste action (scrcpy only)
- `serial` (string): Device serial number
- `text` (string, required): Text to set in the clipboard

Output parameters:

- `message` (string): Human-readable description of the result
- `source` (string): Mechanism used to set the clipboard (scrcpy or adb)
- `success` (boolean): Whether the clipboard was set

### `ui_dump` (~41 tokens)

Dump the full UI hierarchy of the current screen as XML. Useful for understanding screen structure before using ui_find_element.

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `xml` (string): The UI hierarchy as a uiautomator XML document

### `ui_find_element` (~136 tokens)

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.

Input parameters:

- `className` (string): Class name to match exactly (e.g., 'android.widget.Button')
- `contentDesc` (string): Content description to search for (partial match, case-insensitive)
- `resourceId` (string): Resource ID to match exactly (e.g., 'com.app:id/button')
- `serial` (string): Device serial number
- `text` (string): Text content to search for (partial match, case-insensitive)

Output parameters:

- `count` (integer): Number of matching elements
- `elements` (array): Matching UI elements with tap coordinates

### `shell_exec` (~59 tokens)

Execute an arbitrary ADB shell command on the device and return the output. Use this for any device operation not covered by other tools.

Input parameters:

- `command` (string, required): Shell command to execute on the device
- `serial` (string): Device serial number

Output parameters:

- `output` (string): Combined stdout/stderr text from the command

### `file_push` (~69 tokens)

Push a file from the host machine to the device.

Input parameters:

- `localPath` (string, required): Absolute path to the file on the host machine
- `remotePath` (string, required): Destination path on the device (e.g., /sdcard/myfile.txt)
- `serial` (string): Device serial number

Output parameters:

- `message` (string): adb push result or a confirmation message
- `success` (boolean): Whether the file was pushed

### `file_pull` (~69 tokens)

Pull a file from the device to the host machine.

Input parameters:

- `localPath` (string, required): Destination absolute path on the host machine
- `remotePath` (string, required): Path to the file on the device (e.g., /sdcard/myfile.txt)
- `serial` (string): Device serial number

Output parameters:

- `message` (string): adb pull result or a confirmation message
- `success` (boolean): Whether the file was pulled

### `file_list` (~47 tokens)

List directory contents on the device.

Input parameters:

- `path` (string, required): Absolute path to the directory on the device (e.g., /sdcard/)
- `serial` (string): Device serial number

Output parameters:

- `count` (integer): Number of entries returned
- `entries` (array): Directory entries
- `path` (string): The directory that was listed

### `start_video_stream` (~67 tokens)

Start an HTTP MJPEG video stream of the device screen and open a viewer window (ffplay). Starts a scrcpy session automatically if needed.

Input parameters:

- `port` (integer): HTTP port for the MJPEG stream (default 7183)
- `serial` (string): Device serial number

Output parameters:

- `screenSize` (object): Native display resolution — tap/swipe use these native coordinates (no scaling)
- `status` (string): Stream status (e.g. 'started')
- `url` (string): HTTP URL of the MJPEG stream
- `viewer` (string): Viewer status message

### `stop_video_stream` (~35 tokens)

Stop the HTTP MJPEG video stream and close the viewer window for a device.

Input parameters:

- `serial` (string): Device serial number

Output parameters:

- `message` (string): Human-readable status message
- `status` (string): Stream status (e.g. 'stopped')

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/juancf-scrcpy-mcp/scrcpy-mcp#diagnostics

## Score history

- 2026-08-03: 80
- 2026-08-02: 76
- 2026-08-01: 21
- 2026-07-31: 28
- 2026-07-30: 46
- 2026-07-28: 46
- 2026-07-27: 46

## Links

- npm package: https://www.npmjs.com/package/scrcpy-mcp
- Socket report: https://socket.dev/npm/package/scrcpy-mcp
- Repository: https://github.com/JuanCF/scrcpy-mcp
- Changelog RSS feed: https://verifymcp.io/servers/juancf-scrcpy-mcp/scrcpy-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/juancf-scrcpy-mcp/scrcpy-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/juancf-scrcpy-mcp/scrcpy-mcp