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

• 36 tools covering screenshots, input, apps, UI automation, shell, files, clipboard, and video streaming
• scrcpy-first: uses scrcpy's binary control protocol for 10-50x faster input and near-instant screenshots (~33ms)
• ADB fallback: every tool works without scrcpy — slower but always available
• Image-returning screenshots: the AI actually sees the screen, not just a file path
• UI element finding: ui_find_element returns tap coordinates so the AI can act on what it sees
• Clipboard that works on Android 10+: scrcpy bypasses the restrictions that break ADB-only solutions

Prerequisites

Required

Requirement	Install	Verify
Node.js 22+	nodejs.org or nvm install (uses .node_version)	node --version
ADB (Android Platform Tools)	developer.android.com/tools/releases/platform-tools	adb version
Android device with USB debugging	Settings → Developer Options → USB Debugging	adb devices

Optional (for enhanced performance)

Requirement	Install	Benefit
scrcpy	github.com/Genymobile/scrcpy	10-50x faster input, ~33ms screenshots
ffmpeg	apt install ffmpeg / brew install ffmpeg	Required for scrcpy video stream decoding

Device setup

1. Enable Developer Options: Settings → About Phone → tap "Build Number" 7 times
2. Enable USB Debugging: Settings → Developer Options → USB Debugging
3. Connect device via USB
4. Accept the RSA fingerprint prompt on the device
5. Verify: adb devices should show your device as device (not unauthorized)

Installation

# Run directly with npx (no install needed)
npx scrcpy-mcp

# Or install globally
npm install -g scrcpy-mcp

MCP Client Configuration

Claude Code

claude mcp add android -- npx scrcpy-mcp

Or 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 in opencode.json.

Tool Reference

Session Management

Tool	Description
start_session	Start a scrcpy session. When active, input and screenshots use the fast path (10-50x faster).
stop_session	Stop the scrcpy session. Tools fall back to ADB.

Video Streaming

Tool	Description
start_video_stream	Start an HTTP MJPEG video stream and open an ffplay viewer window. Auto-starts a scrcpy session if needed.
stop_video_stream	Stop the video stream and close the viewer window.

Device Management

Tool	Description
device_list	List all connected devices with serial, state, and model
device_info	Get model, Android version, screen size, SDK level, battery
screen_on	Wake the device screen
screen_off	Turn the screen off
rotate_device	Rotate the screen (requires active session)
expand_notifications	Pull down the notification panel (requires active session)
expand_settings	Pull down the quick settings panel (requires active session)
collapse_panels	Collapse notification/settings panels (requires active session)

Vision

Tool	Description
screenshot	Capture the screen and return it as an image. ~33ms with scrcpy, ~500ms via ADB.
screen_record_start	Start recording the screen to a file on the device
screen_record_stop	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	Tap at screen coordinates
swipe	Swipe from one point to another
long_press	Long press at coordinates
drag_drop	Drag from one point to another
input_text	Type a text string into the focused field
key_event	Send a key event: HOME, BACK, ENTER, VOLUME_UP, VOLUME_DOWN, POWER, etc.
scroll	Scroll at a position (dx=horizontal, dy=vertical)

App Management

Tool	Description
app_start	Launch an app by package name. Prefix with + to force-stop before launch.
app_stop	Force-stop an app
app_install	Install an APK from the host machine
app_uninstall	Uninstall an app
app_list	List installed packages, optionally filter by name or system/third-party
app_current	Get the current foreground app and activity

UI Automation

Tool	Description
ui_dump	Dump the full UI hierarchy as XML
ui_find_element	Find elements by text, resource ID, class name, or content description. Returns tap coordinates.

Shell & Files

Tool	Description
shell_exec	Execute an arbitrary ADB shell command and return the output
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

Clipboard

Tool	Description
clipboard_get	Get clipboard content. Uses scrcpy to bypass Android 10+ restrictions.
clipboard_set	Set clipboard content. Pass paste: true to also paste immediately.

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
ADB_PATH	adb	Path to the ADB binary
ANDROID_SERIAL	(none)	Default device serial, overrides auto-detection
SCRCPY_SERVER_PATH	(auto)	Path to the scrcpy-server binary
SCRCPY_SERVER_VERSION	(auto)	Version of the scrcpy-server binary
FFMPEG_PATH	ffmpeg	Path to the ffmpeg binary
FFPLAY_PATH	ffplay	Path to the ffplay binary (for the video stream viewer)

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_PATH points directly to the scrcpy-server file 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.jar on the Android device might have been created as a folder. Run adb shell rm -rf /data/local/tmp/scrcpy-server.jar to delete it.
• Version Mismatch: The client must send the exact version of the scrcpy-server file. The version is resolved in this order: SCRCPY_SERVER_VERSION if set, then scrcpy --version on PATH, then a scrcpy (or scrcpy.exe) executable sitting next to the resolved scrcpy-server, then a built-in default. So on Windows, or when a GUI app launches the MCP without your shell PATH, pointing SCRCPY_SERVER_PATH at a server inside a complete scrcpy install is enough on its own — note that reaching that last step runs the adjacent executable to read its version, so point SCRCPY_SERVER_PATH only 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 nothing resolves (for example a lone scrcpy-server downloaded from the releases page, with no scrcpy beside it), the client falls back to the default version and the server may exit with a version-mismatch error; set SCRCPY_SERVER_VERSION to your installed version (e.g., "4.1"). Run the version tool 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.

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