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

Optional (for enhanced performance)

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 or forcing a specific version), 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",
        "SCRCPY_SERVER_VERSION": "3.3.4"
      }
    }
  }
}

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

Video Streaming

Device Management

Vision

Input Control

All input tools use scrcpy (~5-10ms) when a session is active, otherwise fall back to ADB (~100-300ms).

App Management

UI Automation

Shell & Files

Clipboard

Performance

Start a session once at the beginning to unlock the fast path:

start_session → take screenshots → tap → swipe → ...

Environment Variables

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. Set SCRCPY_SERVER_PATH if it's in a non-standard location.

• 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: Ensure SCRCPY_SERVER_VERSION matches the exact version of the scrcpy-server file (e.g., "3.3.4"). If they mismatch, the Android JVM will fail with java.lang.ClassNotFoundException: com.genymobile.scrcpy.Server.

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