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_start and the video stream require scrcpy)
• 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
• Audio 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

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), 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

start_session options:

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

Audio Streaming & Recording

Heads up: Audio capture is opt-in and requires Android 11+. The default source output uses REMOTE_SUBMIX, which mutes the device's own speakers while capturing — the audio is moved to the host, not copied. Use audioSource: "playback" with audioDup: true (Android 13+) to keep the device audible. Recordings are saved on the host filesystem.

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