Skip to main content
Glama

scrcpy-mcp

MCP server: hela-receptor · Version: 3.0.6 · Canonical tools: 46. Current tool reference.

Part of the HeLa MCP Ecosystem — This server is HeLa Receptor (hela-receptor) — the Mobile component of the HeLa cellular architecture. See the ecosystem docs for profiles, workflows, and multi-client setup.

MCP server for Android device control via ADB and scrcpy. Gives AI agents vision and control over Android devices.

Blotcat acting as a puppeteer, controlling an Android phone with strings

Requirements

  • Node.js >= 22

  • ADB on PATH (or set ADB_PATH)

  • scrcpy-server.jar (v3.x or v4.x) — ships with scrcpy

  • ffmpeg — for H.264 decode and screenshots (optional, ffmpeg-static npm dep available)

  • ffplay — for live video viewer (optional)

Related MCP server: scrcpy-mcp

Install

npm install
npm run build

Run

node dist/server.js

Or with npx:

npx @modelcontextprotocol/inspector node dist/server.js

MCP Configuration

Add to your MCP client config:

{
  "mcpServers": {
    "scrcpy": {
      "command": "node",
      "args": ["/path/to/scrcpy-mcp/dist/server.js"],
      "env": {
        "SCRCPY_SERVER_PATH": "/usr/local/lib/scrcpy-v4.0/scrcpy-server"
      }
    }
  }
}

Tools

Session

Tool

Action

start_session

Start scrcpy session for fast input/screenshots (10-50x faster). Pushes server, sets up ADB forward tunnel, connects video+control sockets. Idempotent.

stop_session

Stop session, fall back to ADB commands

version

Report scrcpy version and resolution source (env/binary/default)

Device

Tool

Action

device_list

List connected devices with state and model

device_info

Model, Android version, SDK, screen size, battery

screen_on

Wake screen (scrcpy power message or KEYCODE_WAKEUP)

screen_off

Turn screen off

connect_wifi

Enable Wi-Fi ADB and connect wirelessly

disconnect_wifi

Disconnect wireless ADB

rotate_device

Rotate screen (needs active session)

expand_notifications

Expand notification panel

expand_settings

Expand quick settings

collapse_panels

Collapse all panels

Vision

Tool

Action

screenshot

Capture screen. Returns scrcpy frame (JPEG) when session active, adb screencap (PNG) otherwise.

screen_record_start

Start screenrecord on device

screen_record_stop

Stop and optionally pull recording to host

Input

Blotcat moving at lightning speed leaving afterimages while tapping an Android phone

Coordinate tools accept native display coordinates matching ui_dump bounds.

Tool

Action

tap

Tap at (x, y). scrcpy fast path -> ADB fallback.

swipe

Swipe from (x1,y1) to (x2,y2) with duration

long_press

Long press at (x, y) with duration

drag_drop

Drag from (x1,y1) to (x2,y2). Uses input draganddrop (API 26+) or swipe fallback.

input_text

Type text. Reports screen state, current app, session status. Auto-wakes screen if off. Auto-focuses input field. When submit=true, finds send button (by content-desc or resource-id) and taps it.

key_event

Send key event by name (HOME, BACK, ENTER, etc.) or keycode

scroll

Scroll at position with dx/dy delta

App Management

Tool

Action

app_start

Launch app by package name. Prefix with + to force-stop first (e.g. +com.example.app). Uses scrcpy START_APP when session active, ADB monkey otherwise.

app_stop

Force-stop app

app_install

Install APK from host path

app_uninstall

Uninstall by package name

app_list

List installed packages with optional filter and system/third-party scoping

app_current

Get foreground app package and activity

Clipboard

Tool

Action

clipboard_get

Read clipboard. scrcpy GET_CLIPBOARD (Android 10+) -> ADB with multiple parsing strategies.

clipboard_set

Set clipboard text. Optional paste flag with scrcpy session.

UI

Blotcat using a magnifying glass to inspect an Android phone broken down into wireframe building blocks

All UI tools use uiautomator dump --compressed under the hood.

Tool

Action

ui_dump

Raw UI hierarchy XML

ui_find_element

Find elements by text, resource-id, class, or content-desc. text matching falls back to content-desc if no text match found. Returns coordinates for each match.

ui_tap_element

Find element and tap it

ui_get_state

Token-efficient Markdown-like tree showing clickable elements and text

ui_wait_for_element

Poll UI until element appears or timeout (default 15s)

ui_smart_fill

Find element -> tap -> type text -> optional ENTER in one call

Shell

Tool

Action

shell_exec

Run arbitrary ADB shell command

File

Tool

Action

file_push

Copy file from host to device

file_pull

Copy file from device to host

file_list

List directory with permissions, owner, size, date

Video Streaming

Tool

Action

start_video_stream

Start HTTP MJPEG stream at http://127.0.0.1:<port> and open ffplay viewer. Auto-starts session if needed. Default port 7183.

stop_video_stream

Stop stream and close viewer

Environment Variables

Variable

Default

Purpose

ADB_PATH

adb

ADB executable path

ANDROID_SERIAL

—

Default device serial

SCRCPY_SERVER_VERSION

3.3.4

Override scrcpy server version

SCRCPY_SERVER_PATH

auto-detect

Path to scrcpy-server.jar

FFMPEG_PATH

ffmpeg-static or system ffmpeg

ffmpeg binary

FFPLAY_PATH

ffplay

ffplay binary

HELA_RECEPTOR_ALLOW_SHELL

unset = off

Set to true to opt in to shell_exec when the active HeLa profile permits android-shell. Restricted profiles block the tool regardless of this flag.

HELA_ENVELOPE

unset = off

Set to true to wrap tool results in the canonical HeLaResult envelope (ok/summary/data/artifacts/provenance/warnings/sideEffects/execution; image blocks and structuredContent preserved). Off = byte-identical legacy output. Run/step ids propagate from HELA_RUN_ID/HELA_STEP_ID.

Architecture

src/
  server.ts          — MCP server init, StdioServerTransport
  core/
    adb.ts           — ADB abstraction layer
    constants.ts     — Protocol constants, defaults
    scrcpy.ts        — Session lifecycle, control messages, video pipeline
    mjpeg.ts         — HTTP MJPEG stream server
  tools/
    session.ts       — start_session, stop_session, version
    device.ts        — device info, screen, rotation, panels, Wi-Fi
    vision.ts        — screenshot, screen recording
    input.ts         — tap, swipe, input_text, key_event, scroll, drag
    apps.ts          — app lifecycle and listing
    clipboard.ts     — clipboard get/set
    ui.ts            — UI hierarchy dump and element search
    shell.ts         — arbitrary ADB shell
    files.ts         — file push/pull/list
    video.ts         — MJPEG stream control

Scrcpy sessions

Two sockets per session: video (raw H.264 from device encoder) and control (binary control messages). ffmpeg decodes H.264 to MJPEG frames in memory for screenshots and the HTTP stream. When video is unavailable (no encoder), control tools and ADB fallback still work.

Coordinate spaces

Callers use native display coordinates (matches wm size and ui_dump bounds). The input system scales these into the downscaled encoder frame size before sending over scrcpy. Without a session, coordinates pass directly to adb shell input tap.

Device Requirements

  • USB debugging enabled

  • ADB authorized (one-time screen tap)

  • Screen can be dead/broken after authorization

  • Wireless: connect_wifi enables TCP mode and connects

License

MIT

The MCP wrapper is distributed under the MIT License. The bundled classes.dex contains compiled scrcpy server components from Genymobile and remains covered by the Apache License 2.0; see THIRD-PARTY-NOTICES and LICENSES/Apache-2.0.

Available Tools

46 tools
app_currentA
Read-only

Get the currently foregrounded app package name and activity.

Inputs: serial. Returns: activity, packageName

app_installB
Idempotent

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

Inputs: apkPath (required), serial. Returns: message, success

app_listA
Read-only

List installed packages on the device. Optionally filter by name or restrict to system/third-party apps. Use to find package names for app_start.

Inputs: filter, serial, system. Returns: count, packages

app_startA

Launch an app by package name. PREFERRED over swiping the app drawer / manual UI navigation. Uses scrcpy START_APP (fast) when session is active, falls back to ADB am start. Supports force-stop prefix (+).

Inputs: serial, package, packageName. Returns: source, message, success

app_stopC
Idempotent

Force-stop an app on the device.

Inputs: packageName (required), serial. Returns: message, success

app_uninstallA
DestructiveIdempotent

Uninstall an app from the device.

Inputs: packageName (required), serial. Returns: message, success

clipboard_getA
Read-only

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.

Inputs: serial. Returns: source, content

clipboard_setA
Idempotent

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.

Inputs: text (required), paste, serial. Returns: source, message, success

collapse_panelsA
Idempotent

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

Inputs: serial. Returns: message, success

connect_wifiA
Idempotent

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

Inputs: port, serial. Returns: address, message, success

device_infoA
Read-only

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

Inputs: serial. Returns: brand, model, serial, sdkLevel, +5 more

device_listA
Read-only

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

Inputs: no named parameters. Returns: count, devices

disconnect_wifiB
Idempotent

Disconnect from a wireless ADB device

Inputs: address (required). Returns: message, success

drag_dropB

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.

Inputs: endX (required), endY (required), startX (required), startY (required), +2 more. Returns: message, success

expand_notificationsA
Idempotent

Expand the notification panel (requires active scrcpy session)

Inputs: serial. Returns: message, success

expand_settingsA
Idempotent

Expand the quick settings panel (requires active scrcpy session)

Inputs: serial. Returns: message, success

file_listB
Read-only

List directory contents on the device.

Inputs: path (required), serial. Returns: path, count, entries

file_pullC
DestructiveIdempotent

Pull a file from the device to the host machine.

Inputs: localPath (required), remotePath (required), serial. Returns: message, success

file_pushA
DestructiveIdempotent

Push a file from the host machine to the device.

Inputs: localPath (required), remotePath (required), serial. Returns: message, success

form_fillB

Fill a multi-field form. Provide an array of {label, value} pairs. For each pair, finds the nearest input field to the label text, taps it, and types the value. Handles checkboxes and dropdowns by label matching.

Inputs: fields (required), serial. Returns: errors, filled

input_textA

Type text into the input field. Reports device context (screen, app, session). When submit=true, auto-detects and taps the send button. Optionally target a specific input field by text label, resource ID, or content description instead of auto-focus.

Inputs: text (required), serial, submit, elementId, +2 more. Returns: focused, message, success, screenOn, +3 more

key_eventB

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

Inputs: key, serial, keycode. Returns: message, success

long_pressB

Perform a long press at the specified coordinates

Inputs: x (required), y (required), serial, duration. Returns: message, success

rotate_deviceA

Rotate the device screen (requires active scrcpy session)

Inputs: serial. Returns: message, success

screen_offB
Idempotent

Turn the device screen off

Inputs: serial. Returns: message, success

screen_onA
Idempotent

Wake the device screen (turn screen on)

Inputs: serial. Returns: message, success

screen_record_startA

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

Inputs: serial, duration, remotePath. Returns: message, success, remotePath

screen_record_stopB
Idempotent

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

Inputs: serial, localPath, pullToHost. Returns: message, success, localPath

screenshotA
Read-only

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

Inputs: serial. Returns: source, encoding, mimeType

scrollA

Scroll at the specified position. dy=negative scrolls UP (reveals content above), dy=positive scrolls DOWN (reveals content below). Use large values (e.g. -400, 500) for meaningful scroll distance.

Inputs: x (required), y (required), dx (required), dy (required), +1 more. Returns: message, success

scroll_to_elementB

Scroll the page to bring a specific UI element into view. Tries to find the element by text, then swipes up/down until it becomes visible or timeout is reached.

Inputs: text (required), serial, direction, maxScrolls. Returns: found, message

shell_execA
Destructive

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

Inputs: command (required), serial. Returns: output

start_sessionA

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.

Inputs: maxFps, serial, maxSize. Returns: serial, status, message, screenSize, +1 more

start_video_streamA

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

Inputs: port, serial. Returns: url, status, viewer, screenSize

stop_sessionA
Idempotent

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

Inputs: serial. Returns: message, success

stop_video_streamA
Idempotent

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

Inputs: serial. Returns: status, message

swipeB

Perform a swipe gesture from one point to another

Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +2 more. Returns: message, success

tapB

Tap at the specified screen coordinates

Inputs: x (required), y (required), serial. Returns: message, success

ui_dumpA
Read-only

Dump the full UI hierarchy of the current screen as XML.

Inputs: serial. Returns: xml

ui_find_elementA
Read-only

Find UI elements on screen by text, resource ID, class name, or content description. Returns matching elements with their tap coordinates.

Inputs: text, serial, className, exactMatch, +2 more. Returns: count, elements

ui_get_stateA
Read-only

Dump the UI and return a clean Markdown-like tree of visible and clickable elements with viewport coordinates. NOTE: WebView elements may report identical y-coordinates when scrolled; use scroll_to_element first to bring target fields into view.

Inputs: serial. Returns: state

ui_smart_fillA

Find a UI element, tap it, inject text, and optionally press ENTER. Smartly finds the nearest input field when targeting a label.

Inputs: textToType (required), text, index, serial, +5 more. Returns: message, success

ui_tap_elementA

Find a UI element by text, resource ID, class name, or content description, and immediately tap it. Smartly finds the nearest input field when targeting a label.

Inputs: text, index, serial, className, +4 more. Returns: message, success

ui_wait_for_elementB
Read-only

Wait for a UI element to appear on screen. Polls the UI until the element matches criteria or timeout is reached.

Inputs: text, serial, className, timeoutMs, +3 more. Returns: message, success

versionA
Read-only

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.

Inputs: no named parameters. Returns: source, version

waitA
Read-only

Wait for a specified number of milliseconds. Use between actions to wait for animations, page loads, or network responses.

Inputs: ms (required). Returns: waited

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 46 tools

    Disambiguation4/5

    Tools are largely distinct, with a clear low-level (tap/swipe/scroll) vs element-based (ui_tap_element/ui_smart_fill/scroll_to_element) vs high-level (form_fill) hierarchy that descriptions make explicit. Minor overlap remains between sibling tools like ui_find_element/ui_tap_element and scroll/swipe/scroll_to_element, and shell_exec acts as a catch-all, but overall an agent can pick correctly.

    Naming Consistency3/5

    Two conflicting orderings coexist: verb_noun (start_session, rotate_device, collapse_panels) alongside resource_verb (app_start, device_info, clipboard_get, screen_on, file_push). Bare verbs (tap, swipe, wait, version) add a third style. Still readable, but the mixed conventions reduce predictability.

    Tool Count3/5

    46 tools is high, but the Android-automation domain is genuinely broad and most tools cover real capabilities (apps, files, clipboard, UI inspection, gestures, streaming). A few could be consolidated (screen_on/screen_off, ui_find_element vs ui_tap_element), pushing it into borderline-heavy territory rather than clearly over-scoped.

    Completeness5/5

    Coverage is near-exhaustive: connection/session management, raw and semantic input, app lifecycle (start/stop/install/uninstall/list/current), clipboard get/set, file push/pull/list, screen control and recording/video streaming, plus UI dump/find/wait/scroll and form filling. No obvious dead ends for device control or automation workflows.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A MCP server that enables AI assistants to control Android devices via ADB, supporting device info, screen control, input simulation, app management, shell execution, file transfer, and UI parsing.
      20
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that gives AI agents full vision and control over Android devices via ADB and scrcpy. Supports screenshots, input, apps, UI automation, shell, files, and clipboard.
      38
      801 npm
      141
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that allows AI agents to drive real Android devices via adb, capturing screenshots, reading the live UI tree, and performing actions like tap, swipe, and type.
      13
      5 npm
      1
      Apache 2.0