scrcpy-mcp
Control and automate connected Android devices over ADB/scrcpy, including fast input, screenshots, UI inspection, app/file/clipboard management, shell access, and live MJPEG streaming.
Start/stop scrcpy sessions for faster tap/swipe/text/screenshots; start/stop HTTP MJPEG video streaming with ffplay viewer.
Inspect devices: list devices, get model/Android/battery/screen info, wake/sleep screen, rotate, connect/disconnect Wi-Fi, expand/collapse panels.
Capture vision: take screenshots and start/stop screen recordings, optionally pulling recordings to host.
Send input: tap, swipe, long press, drag/drop, type text with optional submit, key events, scroll.
Manage apps: launch or force-stop apps, install/uninstall APKs, list installed packages, get foreground app/activity.
Read and set device clipboard, optionally simulating paste.
Automate UI: dump hierarchy XML, find/tap/wait for elements, get compact UI state, smart-fill fields, scroll to elements, fill multi-field forms.
Run arbitrary ADB shell commands.
Push, pull, and list files on the device.
Wait between actions for animations, page loads, or network responses.
Provides control and automation of Android devices via ADB and scrcpy, including screen interaction, UI inspection, app management, clipboard access, file transfer, and screen capture/recording.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@scrcpy-mcp take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.

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-staticnpm dep available)ffplay — for live video viewer (optional)
Related MCP server: scrcpy-mcp
Install
npm install
npm run buildRun
node dist/server.jsOr with npx:
npx @modelcontextprotocol/inspector node dist/server.jsMCP 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 scrcpy session for fast input/screenshots (10-50x faster). Pushes server, sets up ADB forward tunnel, connects video+control sockets. Idempotent. |
| Stop session, fall back to ADB commands |
| Report scrcpy version and resolution source (env/binary/default) |
Device
Tool | Action |
| List connected devices with state and model |
| Model, Android version, SDK, screen size, battery |
| Wake screen (scrcpy power message or KEYCODE_WAKEUP) |
| Turn screen off |
| Enable Wi-Fi ADB and connect wirelessly |
| Disconnect wireless ADB |
| Rotate screen (needs active session) |
| Expand notification panel |
| Expand quick settings |
| Collapse all panels |
Vision
Tool | Action |
| Capture screen. Returns scrcpy frame (JPEG) when session active, |
| Start |
| Stop and optionally pull recording to host |
Input

Coordinate tools accept native display coordinates matching ui_dump bounds.
Tool | Action |
| Tap at (x, y). scrcpy fast path -> ADB fallback. |
| Swipe from (x1,y1) to (x2,y2) with duration |
| Long press at (x, y) with duration |
| Drag from (x1,y1) to (x2,y2). Uses |
| Type text. Reports screen state, current app, session status. Auto-wakes screen if off. Auto-focuses input field. When |
| Send key event by name (HOME, BACK, ENTER, etc.) or keycode |
| Scroll at position with dx/dy delta |
App Management
Tool | Action |
| Launch app by package name. Prefix with |
| Force-stop app |
| Install APK from host path |
| Uninstall by package name |
| List installed packages with optional |
| Get foreground app package and activity |
Clipboard
Tool | Action |
| Read clipboard. scrcpy GET_CLIPBOARD (Android 10+) -> ADB with multiple parsing strategies. |
| Set clipboard text. Optional |
UI

All UI tools use uiautomator dump --compressed under the hood.
Tool | Action |
| Raw UI hierarchy XML |
| Find elements by text, resource-id, class, or content-desc. |
| Find element and tap it |
| Token-efficient Markdown-like tree showing clickable elements and text |
| Poll UI until element appears or timeout (default 15s) |
| Find element -> tap -> type text -> optional ENTER in one call |
Shell
Tool | Action |
| Run arbitrary ADB shell command |
File
Tool | Action |
| Copy file from host to device |
| Copy file from device to host |
| List directory with permissions, owner, size, date |
Video Streaming
Tool | Action |
| Start HTTP MJPEG stream at |
| Stop stream and close viewer |
Environment Variables
Variable | Default | Purpose |
|
| ADB executable path |
| — | Default device serial |
|
| Override scrcpy server version |
| auto-detect | Path to scrcpy-server.jar |
| ffmpeg-static or system | ffmpeg binary |
|
| ffplay binary |
| unset = off | Set to |
| unset = off | Set to |
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 controlScrcpy 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_wifienables 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 toolsapp_currentARead-only
Get the currently foregrounded app package name and activity.
Inputs: serial. Returns: activity, packageName
app_installBIdempotent
Install an APK file on the device from the host machine.
Inputs: apkPath (required), serial. Returns: message, success
app_listARead-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_stopCIdempotent
Force-stop an app on the device.
Inputs: packageName (required), serial. Returns: message, success
app_uninstallADestructiveIdempotent
Uninstall an app from the device.
Inputs: packageName (required), serial. Returns: message, success
clipboard_getARead-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_setAIdempotent
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_panelsAIdempotent
Collapse all open panels (notification, settings) (requires active scrcpy session)
Inputs: serial. Returns: message, success
connect_wifiAIdempotent
Enable WiFi ADB and connect to the device wirelessly. Returns the connection address.
Inputs: port, serial. Returns: address, message, success
device_infoARead-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_listARead-only
List all connected Android devices with their serial numbers, state, and model
Inputs: no named parameters. Returns: count, devices
disconnect_wifiBIdempotent
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_notificationsAIdempotent
Expand the notification panel (requires active scrcpy session)
Inputs: serial. Returns: message, success
expand_settingsAIdempotent
Expand the quick settings panel (requires active scrcpy session)
Inputs: serial. Returns: message, success
file_listBRead-only
List directory contents on the device.
Inputs: path (required), serial. Returns: path, count, entries
file_pullCDestructiveIdempotent
Pull a file from the device to the host machine.
Inputs: localPath (required), remotePath (required), serial. Returns: message, success
file_pushADestructiveIdempotent
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_offBIdempotent
Turn the device screen off
Inputs: serial. Returns: message, success
screen_onAIdempotent
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_stopBIdempotent
Stop screen recording and optionally pull the file to the host.
Inputs: serial, localPath, pullToHost. Returns: message, success, localPath
screenshotARead-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_execADestructive
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_sessionAIdempotent
Stop the active scrcpy session. Tools will fall back to ADB commands.
Inputs: serial. Returns: message, success
stop_video_streamAIdempotent
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_dumpARead-only
Dump the full UI hierarchy of the current screen as XML.
Inputs: serial. Returns: xml
ui_find_elementARead-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_stateARead-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_elementBRead-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
versionARead-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
waitARead-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
Scored across 46 tools
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.
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.
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.
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
Related MCP Connectors
Give your Grok Bot a phone: an MCP server to see and use your phone. Also works with Claude.
1Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
Mobile sandboxes for AI agents: each agent gets its own cloud Android phone or iOS simulator over MCP, reads the screen, taps, types and installs your app. Android $0.01/min, iOS $0.03/min, parked phones free.
Cloud Android phones for AI agents: create a phone, read the screen, tap, type, install APKs, park.
Related MCP Servers
- AlicenseAqualityCmaintenanceA 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.20MIT
- AlicenseAqualityBmaintenanceMCP 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.38801 npm141MIT
- FlicenseAqualityDmaintenanceAn MCP server designed for Android development, enabling AI assistants to directly control Android devices for screenshots, UI analysis, app management, and more.19-
- AlicenseBqualityDmaintenanceAn 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.135 npm1Apache 2.0