scrcpy-mcp

scrcpy-mcp

MCP 服务，通过 ADB 和 scrcpy 为 AI Agent 提供对 Android 设备的完整视觉能力和控制能力。

将任何兼容 MCP 的 AI 助手（Claude Code、OpenCode、Cursor、VS Code Copilot 等）连接到 Android 设备。AI 可以查看屏幕、点击、滑动、输入文字、启动应用、检查 UI 元素、传输文件以及运行 shell 命令。

功能

• 44 个工具，涵盖屏幕截图、输入、应用、UI 自动化、shell、文件、剪贴板、视频流以及音频流/录制
• 优先使用 scrcpy：通过 scrcpy 的二进制控制协议，实现快 10-50 倍的输入响应速度和近乎即时的屏幕截图（约 33ms）
• ADB 回退：交互工具无需 scrcpy 也能工作——速度较慢，但始终可用（音频工具 start_audio_stream/audio_record_start 和视频流需要 scrcpy）
• 返回图像的屏幕截图：AI 可以实际看到屏幕，而不仅仅是文件路径
• 查找 UI 元素：ui_find_element 会返回点击坐标，让 AI 可以对所见内容采取操作
• 音频流和录制：将设备音频流传输到主机扬声器（start_audio_stream），或录制为 .wav/.opus（audio_record_start）
• 适用于 Android 10 及更高版本的剪贴板：scrcpy 绕过了会导致仅使用 ADB 的方案失效的限制

先决条件

必需

要求	安装	验证
Node.js 24+	nodejs.org 或 nvm install（使用 .nvmrc）	node --version
ADB（Android Platform Tools）	developer.android.com/tools/releases/platform-tools	adb version
启用了 USB 调试的 Android 设备（音频功能需要 Android 11+）	设置 → 开发者选项 → USB 调试	adb devices

可选（提升性能）

要求	安装	优势
scrcpy	github.com/Genymobile/scrcpy	输入速度快 10-50 倍，屏幕截图约 33ms
ffmpeg	apt install ffmpeg / brew install ffmpeg	解码 scrcpy 视频流、录制音频和捕获音频片段所必需
ffplay	通常与 ffmpeg 一同打包	播放音频和打开 MJPEG 查看器窗口所必需

设备设置

1. 启用开发者选项：设置 → 关于手机 → 连续点按“版本号” 7 次
2. 启用 USB 调试：设置 → 开发者选项 → USB 调试
3. 通过 USB 连接设备
4. 在设备上接受 RSA 指纹提示
5. 验证：adb devices 应显示设备状态为 device（而非 unauthorized）

安装

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

# Or install globally
npm install -g scrcpy-mcp

MCP 客户端配置

Claude Code

claude mcp add android -- npx scrcpy-mcp

或者，将以下内容添加到项目根目录中的 .mcp.json：

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"]
    }
  }
}

OpenCode

添加到 .mcp.json：

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"]
    }
  }
}

Cursor

设置 → MCP → 添加服务：

{
  "android": {
    "command": "npx",
    "args": ["scrcpy-mcp"]
  }
}

Claude Desktop

编辑 ~/.config/Claude/claude_desktop_config.json（Linux）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"]
    }
  }
}

VS Code（GitHub Copilot）

添加到 .vscode/mcp.json：

{
  "servers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"]
    }
  }
}

自定义环境变量

如果需要配置自定义选项（例如，指定非标准的 scrcpy-server 路径），可以在服务配置中添加 "env" 对象。例如：

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"],
      "env": {
        "SCRCPY_SERVER_PATH": "C:\\path\\to\\scrcpy-server"
      }
    }
  }
}

注意：只有在版本自动检测失败时才设置 SCRCPY_SERVER_VERSION——它会覆盖自动检测，因此过期的值会导致故障排除中所述的版本不匹配问题。请将其设为与你安装的 scrcpy 版本一致（scrcpy --version）。

注意：在 Windows 上，请记得在配置路径中将反斜杠双重转义（\\）。

**OpenCode 用户：**OpenCode 使用 "environment" 而非 "env" 来传递环境变量到 MCP 服务。如果要在 opencode.json 中配置 scrcpy-mcp，请将上方示例中的 "env" 替换为 "environment"。

工具参考

会话管理

工具	描述
start_session	启动 scrcpy 会话。会话激活后，输入和截图会使用快速通道（快 10–50 倍）。
stop_session	停止 scrcpy 会话。工具将回退到 ADB。
version	报告会话推送的 scrcpy-server 版本，以及该版本的解析来源。

start_session 选项：

选项	默认值	描述
maxSize	1024	视频帧的最大尺寸（像素）
maxFps	30	最大帧率
audio	false	捕获音频（参见下方提示）
audioSource	output	音频来源（output、playback、mic、voice-call、……）
audioDup	false	使用 audioSource: "playback" 时，保持设备播放声音（Android 13+）
stayAwake	false	整个会话期间保持设备唤醒（scrcpy --stay-awake）。仅在设备接通电源时生效。
screenOffTimeout	（设备设置）	整个会话期间的屏幕关闭超时时间，单位为秒（scrcpy --screen-off-timeout）。使用电池供电时也有效。需要 scrcpy 2.5+。

这两个保持屏幕唤醒的选项都是临时的：会话结束时，scrcpy 会恢复设备的原始值，包括工具重启会话以启用音频的情况。

视频流

工具	描述
start_video_stream	启动 HTTP MJPEG 视频流并打开查看器窗口（ffplay）。如有需要，会自动启动 scrcpy 会话。
stop_video_stream	停止视频流并关闭查看器窗口。

音频流与录制

提示： 音频捕获为可选功能，需要 Android 11+。默认来源 output 使用 REMOTE_SUBMIX，捕获时会静音设备自身的扬声器——音频会传输到主机，而不是复制一份。使用 audioSource: "playback" 和 audioDup: true（Android 13+）可保持设备发出声音。录音文件保存在主机文件系统中。

工具	描述
start_audio_stream	通过 ffplay 将设备音频流式传输到主机的扬声器。如果 scrcpy 会话启动时未启用音频，则会重启该会话。
stop_audio_stream	停止向主机传输音频流。
audio_record_start	开始在主机上将设备音频录制为 .wav（默认）或 .opus 文件。如有需要，会重启 scrcpy 会话。达到 maxDuration 秒后自动停止（默认值为 300）。
audio_record_stop	停止录制并完成主机端文件的写入。
audio_capture	捕获一段时长有限的设备音频片段，并以音频内容块形式返回。如有需要，会重启 scrcpy 会话。durationSeconds 默认为 5（整数，最大值为 30；当 ffmpeg 不含 libopus 并使用 WAV 回退方案时，默认的 5 秒会变为 2.5 秒）。audioSource/audioDup 默认采用运行中音频会话的设置，因此可以在录制或传输期间获取音频片段，而不会中断会话。

设备管理

工具	描述
device_list	列出所有已连接的设备及其序列号、状态和型号
device_info	获取型号、Android 版本、屏幕尺寸、SDK 级别和电池信息
screen_on	唤醒设备屏幕
screen_off	关闭屏幕
rotate_device	旋转屏幕（需要活动会话）
expand_notifications	下拉通知面板（需要活动会话）
expand_settings	下拉快捷设置面板（需要活动会话）
collapse_panels	收起通知面板/设置面板（需要活动会话）
connect_wifi	启用 WiFi ADB 并以无线方式连接设备。返回连接地址。
disconnect_wifi	断开与无线 ADB 设备的连接

视觉

工具	描述
screenshot	截取屏幕并以图像形式返回。使用 scrcpy 时约需 33ms，通过 ADB 时约需 500ms。
screen_record_start	开始将屏幕录制到设备上的文件中
screen_record_stop	停止录制，并可选择将文件拉取到主机

输入控制

所有输入工具在会话处于活动状态时都使用 scrcpy（约 5-10ms），否则回退到 ADB（约 100-300ms）。

工具	描述
tap	点击屏幕坐标处
swipe	从一个点滑动到另一个点
long_press	长按坐标处
drag_drop	从一个点拖动到另一个点
input_text	在获得焦点的字段中输入文本字符串
key_event	发送按键事件：HOME、BACK、ENTER、VOLUME_UP、VOLUME_DOWN、POWER 等
scroll	在指定位置滚动（dx=水平，dy=垂直）

应用管理

工具	描述
app_start	按包名启动应用。在前面加上 + 可在启动前强制停止应用。
app_stop	强制停止应用
app_install	从主机安装 APK
app_uninstall	卸载应用
app_list	列出已安装的包，可按名称或系统/第三方进行筛选
app_current	获取当前前台应用和活动

UI 自动化

工具	描述
ui_dump	将完整的 UI 层次结构转储为 XML
ui_find_element	按文本、资源 ID、类名或内容描述查找元素。返回点击坐标。

Shell 与文件

工具	描述
shell_exec	执行任意 ADB shell 命令并返回输出
file_push	将文件从主机推送到设备
file_pull	将文件从设备拉取到主机
file_list	列出设备上的目录内容

剪贴板

工具	描述
clipboard_get	获取剪贴板内容。使用 scrcpy 绕过 Android 10+ 的限制。
clipboard_set	设置剪贴板内容。传入 paste: true 还可立即粘贴。

性能

操作	scrcpy（会话活动时）	ADB 回退
截屏	~33ms	~500ms
点击 / 滑动	~5-10ms	~100-300ms
文本输入	~5ms	~100-300ms
剪贴板	~10ms	Android 10+ 上不可靠

在开始时启动一次会话即可启用快速通道：

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

环境变量

变量	默认值	描述
ADB_PATH	adb	ADB 二进制文件的路径
ANDROID_SERIAL	（无）	默认设备序列号，可覆盖自动检测
SCRCPY_SERVER_PATH	（自动）	scrcpy-server 二进制文件的路径
SCRCPY_SERVER_VERSION	（自动）	scrcpy-server 二进制文件的版本
FFMPEG_PATH	ffmpeg	ffmpeg 二进制文件的路径
FFPLAY_PATH	ffplay	ffplay 二进制文件的路径（视频流查看器和音频播放）

仅连接一台设备时，工具会自动检测该设备。连接多台设备时，请显式传入 serial 参数或设置 ANDROID_SERIAL。

故障排除

adb devices 显示 unauthorized 请在设备上接受 RSA 指纹提示。如果未出现提示，请在开发者选项中撤销 USB 调试授权，然后重新连接。 start_session 失败 确保已安装 scrcpy，且可以访问 scrcpy-server 二进制文件。在 Windows 上，将同时包含 scrcpy.exe 和 scrcpy-server 的文件夹添加到 PATH，或将 SCRCPY_SERVER_PATH 设置为 scrcpy-server 文件的完整路径。

• 文件与目录：确保 SCRCPY_SERVER_PATH 直接指向 scrcpy-server 文件本身（例如 C:\path\to\scrcpy-server），而不是其父文件夹。
• Android 目录冲突：如果你之前将目录推送到了服务路径，Android 设备上的 /data/local/tmp/scrcpy-server.jar 可能已被创建为文件夹。运行 adb shell rm -rf /data/local/tmp/scrcpy-server.jar 将其删除。
• 版本不匹配：客户端必须发送它推送的 scrcpy-server 文件对应的确切版本。为确保这一点，服务端和版本不会分别解析——解析时会将同一套 scrcpy 安装作为一对，版本取自该安装中的客户端。安装路径按以下顺序查找：如果设置了 SCRCPY_SERVER_PATH，则使用该路径（客户端随后会在服务端旁边查找，或向上一级前缀在 ../../bin/scrcpy 查找）；否则使用 PATH 中的 scrcpy，其服务端会在其旁边或 ../share/scrcpy/scrcpy-server 查找；否则使用包管理器（dpkg、pacman、rpm、apk、brew）报告的安装。符号链接形式的客户端会先解析到其实际目录，再据此查找对应文件，因此像 Homebrew 的 bin/scrcpy 这样的链接会与其指向的安装配对，而不是与链接所在目录配对。如果设置了 SCRCPY_SERVER_VERSION，则会覆盖检测到的版本。因此，在 Windows 上，或 GUI 应用启动 MCP 时无法访问 shell PATH 的情况下，只需将 SCRCPY_SERVER_PATH 指向完整 scrcpy 安装中的服务端即可；即使 PATH 中更靠前的位置有其他 scrcpy，也会优先使用它——请注意，读取版本时会运行该安装中的可执行文件，因此 SCRCPY_SERVER_PATH 只能指向你信任的安装（这与服务端文件本身需要的信任级别相同，因为该文件会被推送到设备并在那里执行）。如果找不到解析出的服务端对应的客户端（例如只有从发布页面下载的 scrcpy-server），客户端会回退到默认版本，服务端可能因版本不匹配而退出；请将 SCRCPY_SERVER_VERSION 设置为你安装的版本（例如 "4.1"）。运行 version 工具，查看正在使用的版本及其解析来源。请参阅上文的环境变量表。

截图速度较慢（约 500 毫秒） 使用 start_session 启动 scrcpy 会话，以启用快速视频流路径。需要 scrcpy 和 ffmpeg。

expand_notifications / expand_settings / collapse_panels 失败 这些工具需要有效的 scrcpy 会话。请先运行 start_session。

长时间自动化操作期间设备屏幕不断关闭 启动会话时设置 stayAwake: true（仅在接通电源时生效）或 screenOffTimeout: <seconds>；后者在使用电池时也有效。会话结束时，两项设置都会恢复。

start_audio_stream 提示找不到 ffplay 安装 ffmpeg（其中包含 ffplay），或将 FFPLAY_PATH 设置为该二进制文件。audio_record_start 和 FFMPEG_PATH 也适用同样的方法。

录制的音频无声 REMOTE_SUBMIX 只能捕获应用实际播放的内容——在没有任何内容播放时录制会得到数字静音，这是正常现象。还要检查设备是否静音，并注意默认的 output 音源会将音频传输到主机，因此捕获期间设备会变安静。使用 audioSource: "playback" 和 audioDup: true（Android 13+）可让设备继续播放声音。

音频工具报告音频不可用 音频捕获需要 Android 11+（SDK 30）。较旧设备仍可通过会话使用视频、输入和剪贴板功能。

Android 10+ 上剪贴板无法使用 Android 10+ 限制了 ADB 剪贴板访问。启动 scrcpy 会话——scrcpy 剪贴板协议可绕过此限制。 连接多个设备 为每个工具传入 serial，或设置 ANDROID_SERIAL 环境变量。

安全

此服务可完全控制已连接的 Android 设备。shell_exec 工具可以运行任意命令，file_push/file_pull 可以读取和写入 shell 用户可访问的任何文件。

• 此服务通过 stdio 在本地运行，不会暴露到网络
• ADB 要求在设备上明确启用 USB 调试
• 设备必须在首次连接时接受主机的 RSA 密钥
• 仅连接你拥有的设备，并信任你正在使用的 AI Agent

许可证

MIT — 请参阅 LICENSE