Skip to content
Back to search

scrcpy-mcp

MCP server for Android device control via ADB and scrcpy — gives AI agents vision and control over Android devices

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/JuanCF/scrcpy-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/JuanCF/scrcpy-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/juancf--scrcpy-mcp/badge.svg)](/listings/juancf--scrcpy-mcp)

HTML

<a href="/listings/juancf--scrcpy-mcp"><img src="/api/listings/juancf--scrcpy-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 349 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # scrcpy-mcp
  2. MCP server that gives AI agents full vision and control over Android devices via ADB and scrcpy.
  3. 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.
  4. [![MCP Badge](https://lobehub.com/badge/mcp/juancf-scrcpy-mcp)](https://lobehub.com/mcp/juancf-scrcpy-mcp)
  5. ## Features
  6. - **44 tools** covering screenshots, input, apps, UI automation, shell, files, clipboard, video streaming, and audio streaming/recording
  7. - **scrcpy-first**: uses scrcpy's binary control protocol for 10-50x faster input and near-instant screenshots (~33ms)
  8. - **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)
  9. - **Image-returning screenshots**: the AI actually sees the screen, not just a file path
  10. - **UI element finding**: `ui_find_element` returns tap coordinates so the AI can act on what it sees
  11. - **Audio streaming & recording**: stream device audio to host speakers (`start_audio_stream`) or capture to `.wav`/`.opus` (`audio_record_start`)
  12. - **Clipboard that works on Android 10+**: scrcpy bypasses the restrictions that break ADB-only solutions
  13. ## Prerequisites
  14. ### Required
  15. | Requirement | Install | Verify |
  16. |-------------|---------|--------|
  17. | **Node.js 24+** | [nodejs.org](https://nodejs.org) or `nvm install` (uses [`.nvmrc`](.nvmrc)) | `node --version` |
  18. | **ADB** (Android Platform Tools) | [developer.android.com/tools/releases/platform-tools](https://developer.android.com/tools/releases/platform-tools) | `adb version` |
  19. | **Android device** with USB debugging (Android 11+ for audio) | Settings → Developer Options → USB Debugging | `adb devices` |
  20. ### Optional (for enhanced performance)
  21. | Requirement | Install | Benefit |
  22. |-------------|---------|---------|
  23. | **scrcpy** | [github.com/Genymobile/scrcpy](https://github.com/Genymobile/scrcpy/releases) | 10-50x faster input, ~33ms screenshots |
  24. | **ffmpeg** | `apt install ffmpeg` / `brew install ffmpeg` | Required for scrcpy video stream decoding, audio recording, and audio clip capture |
  25. | **ffplay** | Usually packaged with ffmpeg | Required for audio playback and the MJPEG viewer window |
  26. ### Device setup
  27. 1. Enable Developer Options: **Settings → About Phone → tap "Build Number" 7 times**
  28. 2. Enable USB Debugging: **Settings → Developer Options → USB Debugging**
  29. 3. Connect device via USB
  30. 4. Accept the RSA fingerprint prompt on the device
  31. 5. Verify: `adb devices` should show your device as `device` (not `unauthorized`)
  32. ## Installation
  33. ```bash
  34. # Run directly with npx (no install needed)
  35. npx scrcpy-mcp
  36. # Or install globally
  37. npm install -g scrcpy-mcp
  38. ```
  39. ## MCP Client Configuration
  40. ### Claude Code
  41. ```bash
  42. claude mcp add android -- npx scrcpy-mcp
  43. ```
  44. Or add to `.mcp.json` in your project root:
  45. ```json
  46. {
  47. "mcpServers": {
  48. "android": {
  49. "command": "npx",
  50. "args": ["scrcpy-mcp"]
  51. }
  52. }
  53. }
  54. ```
  55. ### OpenCode
  56. Add to `.mcp.json`:
  57. ```json
  58. {
  59. "mcpServers": {
  60. "android": {
  61. "command": "npx",
  62. "args": ["scrcpy-mcp"]
  63. }
  64. }
  65. }
  66. ```
  67. ### Cursor
  68. Settings → MCP → Add Server:
  69. ```json
  70. {
  71. "android": {
  72. "command": "npx",
  73. "args": ["scrcpy-mcp"]
  74. }
  75. }
  76. ```
  77. ### Claude Desktop
  78. Edit `~/.config/Claude/claude_desktop_config.json` (Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  79. ```json
  80. {
  81. "mcpServers": {
  82. "android": {
  83. "command": "npx",
  84. "args": ["scrcpy-mcp"]
  85. }
  86. }
  87. }
  88. ```
  89. ### VS Code (GitHub Copilot)
  90. Add to `.vscode/mcp.json`:
  91. ```json
  92. {
  93. "servers": {
  94. "android": {
  95. "command": "npx",
  96. "args": ["scrcpy-mcp"]
  97. }
  98. }
  99. }
  100. ```
  101. ### Customizing Environment Variables
  102. 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:
  103. ```json
  104. {
  105. "mcpServers": {
  106. "android": {
  107. "command": "npx",
  108. "args": ["scrcpy-mcp"],
  109. "env": {
  110. "SCRCPY_SERVER_PATH": "C:\\path\\to\\scrcpy-server"
  111. }
  112. }
  113. }
  114. }
  115. ```
  116. *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](#troubleshooting). Match it to your installed scrcpy (`scrcpy --version`).*
  117. *Note: On Windows, remember to double-escape backslashes (`\\`) in your configuration paths.*
  118. > **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`.
  119. ## Tool Reference
  120. ### Session Management
  121. | Tool | Description |
  122. |------|-------------|
  123. | `start_session` | Start a scrcpy session. When active, input and screenshots use the fast path (10-50x faster). |
  124. | `stop_session` | Stop the scrcpy session. Tools fall back to ADB. |
  125. | `version` | Report which scrcpy-server version the session pushes and where that version was resolved from. |
  126. `start_session` options:
  127. | Option | Default | Description |
  128. |--------|---------|-------------|
  129. | `maxSize` | `1024` | Max video frame dimension in pixels |
  130. | `maxFps` | `30` | Max frames per second |
  131. | `audio` | `false` | Capture audio (see the heads-up below) |
  132. | `audioSource` | `output` | Audio source (`output`, `playback`, `mic`, `voice-call`, …) |
  133. | `audioDup` | `false` | Keep device playback audible with `audioSource: "playback"` (Android 13+) |
  134. | `stayAwake` | `false` | Keep the device on for the whole session (scrcpy `--stay-awake`). Applies **only while the device is plugged in**. |
  135. | `screenOffTimeout` | (device setting) | Screen-off timeout **in seconds** for the whole session (scrcpy `--screen-off-timeout`). Works on battery too. Needs scrcpy 2.5+. |
  136. Both screen-awake options are temporary: scrcpy restores the device's original
  137. values when the session ends, including when a tool restarts the session to
  138. turn audio on.
  139. ### Video Streaming
  140. | Tool | Description |
  141. |------|-------------|
  142. | `start_video_stream` | Start an HTTP MJPEG video stream and open a viewer window (ffplay). Auto-starts a scrcpy session if needed. |
  143. | `stop_video_stream` | Stop the video stream and close the viewer window. |
  144. ### Audio Streaming & Recording
  145. > **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.
  146. | Tool | Description |
  147. |------|-------------|
  148. | `start_audio_stream` | Stream device audio to the host's speakers via ffplay. Restarts the scrcpy session if it was started without audio. |
  149. | `stop_audio_stream` | Stop streaming audio to the host. |
  150. | `audio_record_start` | Start recording device audio to `.wav` (default) or `.opus` on the host. Restarts the scrcpy session if needed. Stops automatically after `maxDuration` seconds (default 300). |
  151. | `audio_record_stop` | Stop the recording and finalise the host-side file. |
  152. | `audio_capture` | Capture a bounded clip of device audio and return it as an audio content block. Restarts the scrcpy session if needed. `durationSeconds` defaults to 5 (integer, max 30; a 5s default becomes 2.5s when ffmpeg has no libopus and the WAV fallback is used). `audioSource`/`audioDup` default to the running audio session's settings, so a clip can be taken during a recording or stream without interrupting it. |
  153. ### Device Management
  154. | Tool | Description |
  155. |------|-------------|
  156. | `device_list` | List all connected devices with serial, state, and model |
  157. | `device_info` | Get model, Android version, screen size, SDK level, battery |
  158. | `screen_on` | Wake the device screen |
  159. | `screen_off` | Turn the screen off |
  160. | `rotate_device` | Rotate the screen (requires active session) |
  161. | `expand_notifications` | Pull down the notification panel (requires active session) |
  162. | `expand_settings` | Pull down the quick settings panel (requires active session) |
  163. | `collapse_panels` | Collapse notification/settings panels (requires active session) |
  164. | `connect_wifi` | Enable WiFi ADB and connect to the device wirelessly. Returns the connection address. |
  165. | `disconnect_wifi` | Disconnect from a wireless ADB device |
  166. ### Vision
  167. | Tool | Description |
  168. |------|-------------|
  169. | `screenshot` | Capture the screen and return it as an image. ~33ms with scrcpy, ~500ms via ADB. |
  170. | `screen_record_start` | Start recording the screen to a file on the device |
  171. | `screen_record_stop` | Stop recording and optionally pull the file to the host |
  172. ### Input Control
  173. All input tools use scrcpy (~5-10ms) when a session is active, otherwise fall back to ADB (~100-300ms).
  174. | Tool | Description |
  175. |------|-------------|
  176. | `tap` | Tap at screen coordinates |
  177. | `swipe` | Swipe from one point to another |
  178. | `long_press` | Long press at coordinates |
  179. | `drag_drop` | Drag from one point to another |
  180. | `input_text` | Type a text string into the focused field |
  181. | `key_event` | Send a key event: HOME, BACK, ENTER, VOLUME_UP, VOLUME_DOWN, POWER, etc. |
  182. | `scroll` | Scroll at a position (dx=horizontal, dy=vertical) |
  183. ### App Management
  184. | Tool | Description |
  185. |------|-------------|
  186. | `app_start` | Launch an app by package name. Prefix with `+` to force-stop before launch. |
  187. | `app_stop` | Force-stop an app |
  188. | `app_install` | Install an APK from the host machine |
  189. | `app_uninstall` | Uninstall an app |
  190. | `app_list` | List installed packages, optionally filter by name or system/third-party |
  191. | `app_current` | Get the current foreground app and activity |
  192. ### UI Automation
  193. | Tool | Description |
  194. |------|-------------|
  195. | `ui_dump` | Dump the full UI hierarchy as XML |
  196. | `ui_find_element` | Find elements by text, resource ID, class name, or content description. Returns tap coordinates. |
  197. ### Shell & Files
  198. | Tool | Description |
  199. |------|-------------|
  200. | `shell_exec` | Execute an arbitrary ADB shell command and return the output |
  201. | `file_push` | Push a file from the host machine to the device |
  202. | `file_pull` | Pull a file from the device to the host machine |
  203. | `file_list` | List directory contents on the device |
  204. ### Clipboard
  205. | Tool | Description |
  206. |------|-------------|
  207. | `clipboard_get` | Get clipboard content. Uses scrcpy to bypass Android 10+ restrictions. |
  208. | `clipboard_set` | Set clipboard content. Pass `paste: true` to also paste immediately. |
  209. ## Performance
  210. | Operation | scrcpy (session active) | ADB fallback |
  211. |-----------|------------------------|--------------|
  212. | Screenshot | ~33ms | ~500ms |
  213. | Tap / Swipe | ~5-10ms | ~100-300ms |
  214. | Text input | ~5ms | ~100-300ms |
  215. | Clipboard | ~10ms | unreliable on Android 10+ |
  216. Start a session once at the beginning to unlock the fast path:
  217. ```
  218. start_session → take screenshots → tap → swipe → ...
  219. ```
  220. ## Environment Variables
  221. | Variable | Default | Description |
  222. |----------|---------|-------------|
  223. | `ADB_PATH` | `adb` | Path to the ADB binary |
  224. | `ANDROID_SERIAL` | (none) | Default device serial, overrides auto-detection |
  225. | `SCRCPY_SERVER_PATH` | (auto) | Path to the scrcpy-server binary |
  226. | `SCRCPY_SERVER_VERSION` | (auto) | Version of the scrcpy-server binary |
  227. | `FFMPEG_PATH` | `ffmpeg` | Path to the ffmpeg binary |
  228. | `FFPLAY_PATH` | `ffplay` | Path to the ffplay binary (video stream viewer and audio playback) |
  229. When only one device is connected, tools auto-detect it. With multiple devices, pass the `serial` parameter explicitly or set `ANDROID_SERIAL`.
  230. ## Troubleshooting
  231. **`adb devices` shows `unauthorized`**
  232. Accept the RSA fingerprint prompt on the device. If the prompt doesn't appear, revoke USB debugging authorizations in Developer Options and reconnect.
  233. **`start_session` fails**
  234. 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.
  235. * **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.
  236. * **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.
  237. * **Version Mismatch**: The client must send the exact version of the `scrcpy-server` file 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_PATH` if set (its client is then located beside the server, or one prefix step away at `../../bin/scrcpy`); otherwise the `scrcpy` on 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's `bin/scrcpy` pairs with the install it points at rather than with the link's own directory. `SCRCPY_SERVER_VERSION` overrides the detected version if set. 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, and it wins even if a different scrcpy comes first on your PATH — note that reading the version **runs that install's executable**, 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 no client can be found for the resolved server (for example a lone `scrcpy-server` downloaded from the releases page), 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.
  238. **Screenshots are slow (~500ms)**
  239. Start a scrcpy session with `start_session` to enable the fast video stream path. Requires scrcpy and ffmpeg.
  240. **`expand_notifications` / `expand_settings` / `collapse_panels` fail**
  241. These tools require an active scrcpy session. Run `start_session` first.
  242. **The device screen keeps turning off during long automations**
  243. Start the session with `stayAwake: true` (plugged in only) or `screenOffTimeout: <seconds>`, which also works on battery. Both are restored when the session ends.
  244. **`start_audio_stream` says ffplay was not found**
  245. Install ffmpeg (ffplay ships with it), or set `FFPLAY_PATH` to the binary. The same applies to `audio_record_start` and `FFMPEG_PATH`.
  246. **Audio recording is silent**
  247. `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.
  248. **Audio tools report audio as unavailable**
  249. Audio capture needs Android 11+ (SDK 30). On older devices the session still works for video, input, and clipboard.
  250. **Clipboard doesn't work on Android 10+**
  251. ADB clipboard access is restricted on Android 10+. Start a scrcpy session — the scrcpy clipboard protocol bypasses this restriction.
  252. **Multiple devices connected**
  253. Pass `serial` to each tool or set the `ANDROID_SERIAL` environment variable.
  254. ## Security
  255. 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.
  256. - The server runs locally over stdio — it is not exposed to the network
  257. - ADB requires USB debugging to be explicitly enabled on the device
  258. - The device must accept your host's RSA key on first connection
  259. - Only connect devices you own and trust the AI agent you are using
  260. ## License
  261. MIT — see [LICENSE](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.