scrcpy-mcp
This server lets AI agents fully control and observe Android devices over ADB/scrcpy, with fast scrcpy-based input/screenshots and ADB fallback.
Start/stop a scrcpy session for 10-50x faster input and ~33ms screenshots
List devices and get device info (model, Android version, screen, SDK, battery)
Control screen: on/off, rotate, expand notifications/settings, collapse panels, connect/disconnect WiFi ADB
Take screenshots, record the screen, and pull recordings to the host
Send taps, swipes, long presses, drag-and-drop, text input, key events, and scrolls
Manage apps: launch, force-stop, install, uninstall, list packages, get foreground app
Automate UI: dump UI hierarchy XML and find elements with tap coordinates
Run arbitrary shell commands and manage files (push, pull, list)
Get/set clipboard content, including Android 10+ via scrcpy
Stream video over MJPEG with a viewer window
Stream or record device audio, capture audio clips, and save recordings on the host
Provides full vision and control over Android devices via ADB and scrcpy, enabling AI agents to interact with the device screen, input, apps, UI, shell, files, and clipboard.
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 of my home screen"
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 that gives AI agents full vision and control over Android devices via ADB and scrcpy.
Connect any MCP-compatible AI assistant (Claude Code, OpenCode, Cursor, VS Code Copilot, etc.) to your Android device. The AI can see the screen, tap, swipe, type, launch apps, inspect UI elements, transfer files, and run shell commands.
Features
44 tools covering screenshots, input, apps, UI automation, shell, files, clipboard, video streaming, and audio streaming/recording
scrcpy-first: uses scrcpy's binary control protocol for 10-50x faster input and near-instant screenshots (~33ms)
ADB fallback: interaction tools work without scrcpy — slower but always available (the audio tools
start_audio_stream/audio_record_startand the video stream require scrcpy)Image-returning screenshots: the AI actually sees the screen, not just a file path
UI element finding:
ui_find_elementreturns tap coordinates so the AI can act on what it seesAudio streaming & recording: stream device audio to host speakers (
start_audio_stream) or capture to.wav/.opus(audio_record_start)Clipboard that works on Android 10+: scrcpy bypasses the restrictions that break ADB-only solutions
Related MCP server: androir-mcp
Prerequisites
Required
Requirement | Install | Verify |
Node.js 24+ | nodejs.org or |
|
ADB (Android Platform Tools) |
| |
Android device with USB debugging (Android 11+ for audio) | Settings → Developer Options → USB Debugging |
|
Optional (for enhanced performance)
Requirement | Install | Benefit |
scrcpy | 10-50x faster input, ~33ms screenshots | |
ffmpeg |
| Required for scrcpy video stream decoding, audio recording, and audio clip capture |
ffplay | Usually packaged with ffmpeg | Required for audio playback and the MJPEG viewer window |
Device setup
Enable Developer Options: Settings → About Phone → tap "Build Number" 7 times
Enable USB Debugging: Settings → Developer Options → USB Debugging
Connect device via USB
Accept the RSA fingerprint prompt on the device
Verify:
adb devicesshould show your device asdevice(notunauthorized)
Installation
# Run directly with npx (no install needed)
npx scrcpy-mcp
# Or install globally
npm install -g scrcpy-mcpMCP Client Configuration
Claude Code
claude mcp add android -- npx scrcpy-mcpOr add to .mcp.json in your project root:
{
"mcpServers": {
"android": {
"command": "npx",
"args": ["scrcpy-mcp"]
}
}
}OpenCode
Add to .mcp.json:
{
"mcpServers": {
"android": {
"command": "npx",
"args": ["scrcpy-mcp"]
}
}
}Cursor
Settings → MCP → Add Server:
{
"android": {
"command": "npx",
"args": ["scrcpy-mcp"]
}
}Claude Desktop
Edit ~/.config/Claude/claude_desktop_config.json (Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"android": {
"command": "npx",
"args": ["scrcpy-mcp"]
}
}
}VS Code (GitHub Copilot)
Add to .vscode/mcp.json:
{
"servers": {
"android": {
"command": "npx",
"args": ["scrcpy-mcp"]
}
}
}Customizing Environment Variables
If you need to configure custom options (such as pointing to a non-standard scrcpy-server path), you can add the "env" object to your server configuration. For example:
{
"mcpServers": {
"android": {
"command": "npx",
"args": ["scrcpy-mcp"],
"env": {
"SCRCPY_SERVER_PATH": "C:\\path\\to\\scrcpy-server"
}
}
}
}Note: only set SCRCPY_SERVER_VERSION if version auto-detection fails — it overrides detection, so a stale value causes the version mismatch described in Troubleshooting. Match it to your installed scrcpy (scrcpy --version).
Note: On Windows, remember to double-escape backslashes (\\) in your configuration paths.
OpenCode users: OpenCode uses
"environment"instead of"env"for passing environment variables to MCP servers. Replace"env"with"environment"in the example above if you're configuring scrcpy-mcp inopencode.json.
Tool Reference
Session Management
Tool | Description |
| Start a scrcpy session. When active, input and screenshots use the fast path (10-50x faster). |
| Stop the scrcpy session. Tools fall back to ADB. |
| Report which scrcpy-server version the session pushes and where that version was resolved from. |
start_session options:
Option | Default | Description |
|
| Max video frame dimension in pixels |
|
| Max frames per second |
|
| Capture audio (see the heads-up below) |
|
| Audio source ( |
|
| Keep device playback audible with |
|
| Keep the device on for the whole session (scrcpy |
| (device setting) | Screen-off timeout in seconds for the whole session (scrcpy |
Both screen-awake options are temporary: scrcpy restores the device's original values when the session ends, including when a tool restarts the session to turn audio on.
Video Streaming
Tool | Description |
| Start an HTTP MJPEG video stream and open a viewer window (ffplay). Auto-starts a scrcpy session if needed. |
| Stop the video stream and close the viewer window. |
Audio Streaming & Recording
Heads up: Audio capture is opt-in and requires Android 11+. The default source
outputusesREMOTE_SUBMIX, which mutes the device's own speakers while capturing — the audio is moved to the host, not copied. UseaudioSource: "playback"withaudioDup: true(Android 13+) to keep the device audible. Recordings are saved on the host filesystem.
Tool | Description |
| Stream device audio to the host's speakers via ffplay. Restarts the scrcpy session if it was started without audio. |
| Stop streaming audio to the host. |
| Start recording device audio to |
| Stop the recording and finalise the host-side file. |
| Capture a bounded clip of device audio and return it as an audio content block. Restarts the scrcpy session if needed. |
Device Management
Tool | Description |
| List all connected devices with serial, state, and model |
| Get model, Android version, screen size, SDK level, battery |
| Wake the device screen |
| Turn the screen off |
| Rotate the screen (requires active session) |
| Pull down the notification panel (requires active session) |
| Pull down the quick settings panel (requires active session) |
| Collapse notification/settings panels (requires active session) |
| Enable WiFi ADB and connect to the device wirelessly. Returns the connection address. |
| Disconnect from a wireless ADB device |
Vision
Tool | Description |
| Capture the screen and return it as an image. ~33ms with scrcpy, ~500ms via ADB. |
| Start recording the screen to a file on the device |
| Stop recording and optionally pull the file to the host |
Input Control
All input tools use scrcpy (~5-10ms) when a session is active, otherwise fall back to ADB (~100-300ms).
Tool | Description |
| Tap at screen coordinates |
| Swipe from one point to another |
| Long press at coordinates |
| Drag from one point to another |
| Type a text string into the focused field |
| Send a key event: HOME, BACK, ENTER, VOLUME_UP, VOLUME_DOWN, POWER, etc. |
| Scroll at a position (dx=horizontal, dy=vertical) |
App Management
Tool | Description |
| Launch an app by package name. Prefix with |
| Force-stop an app |
| Install an APK from the host machine |
| Uninstall an app |
| List installed packages, optionally filter by name or system/third-party |
| Get the current foreground app and activity |
UI Automation
Tool | Description |
| Dump the full UI hierarchy as XML |
| Find elements by text, resource ID, class name, or content description. Returns tap coordinates. |
Shell & Files
Tool | Description |
| Execute an arbitrary ADB shell command and return the output |
| Push a file from the host machine to the device |
| Pull a file from the device to the host machine |
| List directory contents on the device |
Clipboard
Tool | Description |
| Get clipboard content. Uses scrcpy to bypass Android 10+ restrictions. |
| Set clipboard content. Pass |
Performance
Operation | scrcpy (session active) | ADB fallback |
Screenshot | ~33ms | ~500ms |
Tap / Swipe | ~5-10ms | ~100-300ms |
Text input | ~5ms | ~100-300ms |
Clipboard | ~10ms | unreliable on Android 10+ |
Start a session once at the beginning to unlock the fast path:
start_session → take screenshots → tap → swipe → ...Environment Variables
Variable | Default | Description |
|
| Path to the ADB binary |
| (none) | Default device serial, overrides auto-detection |
| (auto) | Path to the scrcpy-server binary |
| (auto) | Version of the scrcpy-server binary |
|
| Path to the ffmpeg binary |
|
| Path to the ffplay binary (video stream viewer and audio playback) |
When only one device is connected, tools auto-detect it. With multiple devices, pass the serial parameter explicitly or set ANDROID_SERIAL.
Troubleshooting
adb devices shows unauthorized
Accept the RSA fingerprint prompt on the device. If the prompt doesn't appear, revoke USB debugging authorizations in Developer Options and reconnect.
start_session fails
Make sure scrcpy is installed and the scrcpy-server binary is accessible. On Windows, add the folder containing both scrcpy.exe and scrcpy-server to your PATH, or set SCRCPY_SERVER_PATH to the full path of the scrcpy-server file.
File vs Directory: Ensure
SCRCPY_SERVER_PATHpoints directly to thescrcpy-serverfile itself (e.g.C:\path\to\scrcpy-server), NOT to its parent folder.Android Directory Conflict: If you previously pushed a directory to the server path,
/data/local/tmp/scrcpy-server.jaron the Android device might have been created as a folder. Runadb shell rm -rf /data/local/tmp/scrcpy-server.jarto delete it.Version Mismatch: The client must send the exact version of the
scrcpy-serverfile it pushes. To guarantee that, the server and the version are never resolved separately — one scrcpy install is resolved as a pair, and the version comes from the client belonging to that same install. The install is found in this order:SCRCPY_SERVER_PATHif set (its client is then located beside the server, or one prefix step away at../../bin/scrcpy); otherwise thescrcpyon your PATH, whose server is located beside it or at../share/scrcpy/scrcpy-server; otherwise whatever your package manager reports (dpkg,pacman,rpm,apk,brew). A symlinked client is resolved to its real directory before its counterpart is derived, so a link farm such as Homebrew'sbin/scrcpypairs with the install it points at rather than with the link's own directory.SCRCPY_SERVER_VERSIONoverrides the detected version if set. So on Windows, or when a GUI app launches the MCP without your shell PATH, pointingSCRCPY_SERVER_PATHat a server inside a complete scrcpy install is enough on its own, and it wins even if a different scrcpy comes first on your PATH — note that reading the version runs that install's executable, so pointSCRCPY_SERVER_PATHonly at an install you trust (the same trust the server file itself already requires, since it gets pushed to your device and executed there). If no client can be found for the resolved server (for example a lonescrcpy-serverdownloaded from the releases page), the client falls back to the default version and the server may exit with a version-mismatch error; setSCRCPY_SERVER_VERSIONto your installed version (e.g.,"4.1"). Run theversiontool to see which version is in use and where it was resolved from. See the Environment Variables table above.
Screenshots are slow (~500ms)
Start a scrcpy session with start_session to enable the fast video stream path. Requires scrcpy and ffmpeg.
expand_notifications / expand_settings / collapse_panels fail
These tools require an active scrcpy session. Run start_session first.
The device screen keeps turning off during long automations
Start the session with stayAwake: true (plugged in only) or screenOffTimeout: <seconds>, which also works on battery. Both are restored when the session ends.
start_audio_stream says ffplay was not found
Install ffmpeg (ffplay ships with it), or set FFPLAY_PATH to the binary. The same applies to audio_record_start and FFMPEG_PATH.
Audio recording is silent
REMOTE_SUBMIX only captures what apps are actually playing — a recording made while nothing plays is digital silence, which is expected. Also check the device is not muted, and remember the default output source moves the audio to the host, so the device goes quiet while capturing. Use audioSource: "playback" with audioDup: true (Android 13+) to keep it audible.
Audio tools report audio as unavailable Audio capture needs Android 11+ (SDK 30). On older devices the session still works for video, input, and clipboard.
Clipboard doesn't work on Android 10+ ADB clipboard access is restricted on Android 10+. Start a scrcpy session — the scrcpy clipboard protocol bypasses this restriction.
Multiple devices connected
Pass serial to each tool or set the ANDROID_SERIAL environment variable.
Security
This server provides full control over connected Android devices. The shell_exec tool can run arbitrary commands, and file_push/file_pull can read and write any file accessible to the shell user.
The server runs locally over stdio — it is not exposed to the network
ADB requires USB debugging to be explicitly enabled on the device
The device must accept your host's RSA key on first connection
Only connect devices you own and trust the AI agent you are using
License
MIT — see LICENSE
Available Tools
38 toolsapp_currentA
Get the currently foregrounded app package name and activity.
Inputs: serial.
app_installB
Install an APK file on the device from the host machine.
Inputs: apkPath (required), serial.
app_listB
List installed packages on the device. Optionally filter by name or restrict to system/third-party apps.
Inputs: filter, system, serial.
app_startA
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.
Inputs: packageName (required), serial.
app_stopB
Force-stop an app on the device.
Inputs: packageName (required), serial.
app_uninstallC
Uninstall an app from the device.
Inputs: packageName (required), serial.
clipboard_getA
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.
clipboard_setA
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.
collapse_panelsA
Collapse all open panels (notification, settings) (requires active scrcpy session)
Inputs: serial.
connect_wifiB
Enable WiFi ADB and connect to the device wirelessly. Returns the connection address.
Inputs: port, serial.
device_infoA
Get detailed info about a device: model, Android version, screen size, SDK level, battery level
Inputs: serial.
device_listA
List all connected Android devices with their serial numbers, state, and model
Inputs: no named parameters.
disconnect_wifiB
Disconnect from a wireless ADB device
Inputs: address (required).
drag_dropA
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: startX (required), startY (required), endX (required), endY (required), +2 more.
expand_notificationsA
Expand the notification panel (requires active scrcpy session)
Inputs: serial.
expand_settingsA
Expand the quick settings panel (requires active scrcpy session)
Inputs: serial.
file_listC
List directory contents on the device.
Inputs: path (required), serial.
file_pullB
Pull a file from the device to the host machine.
Inputs: remotePath (required), localPath (required), serial.
file_pushB
Push a file from the host machine to the device.
Inputs: localPath (required), remotePath (required), serial.
input_textA
Type text into the currently focused input field
Inputs: text (required), serial.
key_eventB
Send a key event to the device. Supports keycodes like HOME, BACK, ENTER, VOLUME_UP, etc.
Inputs: keycode (required), serial.
long_pressC
Perform a long press at the specified coordinates
Inputs: x (required), y (required), duration, serial.
rotate_deviceB
Rotate the device screen (requires active scrcpy session)
Inputs: serial.
screen_offB
Turn the device screen off
Inputs: serial.
screen_onB
Wake the device screen (turn screen on)
Inputs: serial.
screen_record_startA
Start recording the screen. Recording continues until screen_record_stop is called.
Inputs: serial, remotePath, duration.
screen_record_stopA
Stop screen recording and optionally pull the file to the host.
Inputs: serial, pullToHost, localPath.
screenshotA
Take a screenshot of the Android device screen. Returns the image as base64.
Inputs: serial.
scrollB
Scroll at the specified position. dx and dy are scroll amounts (-1 to 1 range approximated for ADB).
Inputs: x (required), y (required), dx (required), dy (required), +1 more.
shell_execA
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.
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: serial, maxSize, maxFps.
start_video_streamB
Start an HTTP MJPEG video stream of the device screen. Opens a native ffplay window that connects to the stream URL. Requires an active scrcpy session.
Inputs: serial, port.
stop_sessionA
Stop the active scrcpy session. Tools will fall back to ADB commands.
Inputs: serial.
stop_video_streamA
Stop the HTTP MJPEG video stream and close the viewer window for a device.
Inputs: serial.
swipeC
Perform a swipe gesture from one point to another
Inputs: x1 (required), y1 (required), x2 (required), y2 (required), +2 more.
tapA
Tap at the specified screen coordinates
Inputs: x (required), y (required), serial.
ui_dumpA
Dump the full UI hierarchy of the current screen as XML. Useful for understanding screen structure before using ui_find_element.
Inputs: serial.
ui_find_elementA
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.
Inputs: text, resourceId, className, contentDesc, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 38 tools
Each tool has a clearly distinct purpose, with categories like app, clipboard, file, screen, input, UI, and session management. Overlaps are minimal and descriptions clarify any potential confusion.
Most tools follow a verb_noun or noun_verb pattern consistently within categories (e.g., app_*, file_*, screen_*). Minor deviations like 'drag_drop' and 'screenshot' are present but do not significantly impact predictability.
38 tools is on the higher side but still justified by the broad scope of device control (apps, files, input, screen, UI, streaming). Paired operations (start/stop) contribute to the count without redundancy.
The tool surface covers app lifecycle, file transfer, input gestures, key events, clipboard, screen management, UI inspection, recording, and streaming. The inclusion of 'shell_exec' as a catch-all ensures no operation is impossible.
Maintenance
Related MCP Connectors
Melaya is a remote MCP server. It gives an assistant hands on your own Android phone and browser: it reads the screen through the accessibility tree, then taps, types and navigates inside the apps and sites you allow-list, with no per-app API. It also builds, schedules and runs agent pipelines across 6k+ connected tools. OAuth 2.1, nothing to install.
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
MCP server for AI agents: posts, messages and comments on WhatsApp, Instagram, TikTok and Facebook.
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
- 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
- AlicenseAqualityDmaintenanceAn MCP server that gives AI agents full control of Android devices and emulators through plain ADB — no companion APK, no extra daemon, no telemetry.2614MIT
- AlicenseBqualityBmaintenanceMCP server for Android device control via ADB and scrcpy, enabling AI agents to see and interact with Android devices.46MIT