Scrcpy Server

Local MCP server that exposes Android device control via adb and scrcpy as 22 tools for MCP clients like Claude Code and Codex CLI.

Quick Start

One command — no prerequisites needed (the installer handles everything):

curl -fsSL https://raw.githubusercontent.com/charettep/scrcpy-mcp/main/install.sh | bash

Or from a local clone:

git clone https://github.com/charettep/scrcpy-mcp.git && cd scrcpy-mcp
./install.sh

The installer will:

1. Detect your OS and package manager (apt, dnf, pacman, brew)
2. Download the repo to ~/mcp/scrcpy-mcp (if running via curl)
3. Check for adb, scrcpy, and uv — install any that are missing
4. Find Python 3.10+ and create an isolated venv with dependencies
5. Detect installed MCP clients (Claude Code, Codex CLI)
6. Ask where to register the server:
   • Global — injects config directly into ~/.claude.json and/or ~/.codex/config.toml
   • Project — generates a local .mcp.json file

Re-running the installer is safe — it updates the existing install and overwrites old config entries.

Prerequisites

• Python 3.10+
• adb (from Android SDK platform-tools)
• scrcpy (for mirroring/recording sessions)
• An Android device with USB debugging enabled

The installer handles all of the above automatically.

Manual Install

If you prefer not to use the installer:

uv venv .venv && uv pip install -r requirements.txt

Then add to your project .mcp.json:

{
  "mcpServers": {
    "scrcpy": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/scrcpy_mcp.py"],
      "env": {
        "SCRCPY_MCP_ADB_PATH": "/usr/bin/adb",
        "SCRCPY_MCP_SCRCPY_PATH": "/usr/bin/scrcpy"
      }
    }
  }
}

The env block is optional — without it, adb and scrcpy are resolved from PATH.

Available Tools (22)

Device Management

Tool	Description
list_devices	List connected devices with status
device_info	Get model, Android version, screen resolution, battery, IP
tcpip_connect	Connect/disconnect device via wireless ADB

Input Injection

Tool	Description
tap	Tap at x,y coordinates
swipe	Swipe from point A to B with duration
key_event	Send key event (BACK, HOME, POWER, etc.)
input_text	Type text string on device
long_press	Long press at coordinates

Screen & Display

Tool	Description
screenshot	Capture screenshot and save locally
screen_power	Turn screen on/off/toggle
rotation	Get/set device rotation
screen_record	Record screen to mp4 file

App Management

Tool	Description
list_apps	List installed packages
start_app	Launch app by package name
stop_app	Force stop an app
install_apk	Install APK file

Clipboard

Tool	Description
get_clipboard	Read device clipboard
set_clipboard	Set device clipboard text

File Transfer

Tool	Description
push_file	Push local file to device
pull_file	Pull file from device

Scrcpy Sessions

Tool	Description
start_mirror	Start scrcpy mirroring with full options
stop_session	Stop a running scrcpy session

Multi-device Support

All tools accept an optional serial parameter. If omitted, adb uses the only connected device (or fails if multiple are connected).

tap(x=500, y=1000, serial="ABCD1234")

Environment Variables

Variable	Purpose	Default
SCRCPY_MCP_ADB_PATH	Absolute path to adb binary	adb (from PATH)
SCRCPY_MCP_SCRCPY_PATH	Absolute path to scrcpy binary	scrcpy (from PATH)

These are set automatically by install.sh via the MCP config env block.

Verify

python3 scrcpy_mcp.py  # starts on stdio
python3 -c "from scrcpy_mcp import mcp; print(len(mcp._tool_manager._tools))"  # should print 22