Scrcpy MCP

scrcpy mcp

MCP服务器，通过ADB和scrcpy为AI代理提供对Android设备的完全视觉和控制。

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

特性

• 34工具 涵盖屏幕截图、输入、应用程序、UI自动化、shell、文件和剪贴板
• scrcpy优先：使用scrcpy的二进制控制协议，输入速度提高10-50倍，屏幕截图近乎即时（约33ms）
• ADB回退：每个工具都可以在没有scrcpy的情况下工作——速度较慢，但始终可用
• 图片返回截图：AI实际上看到的是屏幕，而不仅仅是文件路径
• UI元素查找: ui_find_element 返回点击坐标，以便AI可以根据它看到的内容采取行动
• 适用于Android 10的剪贴板+：scrcpy绕过了打破亚行专用解决方案的限制

先决条件

必需的

可选（用于增强性能）

设备设置

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 mcp add android -- npx scrcpy-mcp

或添加到 .mcp.json 在项目根目录中：

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

开源代码

增添 .mcp.json:

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

光标

设置→ MCP → 添加服务器：

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

克劳德桌面版

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

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

VS代码（GitHub副本）

增添 .vscode/mcp.json:

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

工具参考

会话管理

设备管理

视觉

输入控制

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

应用程序管理

用户界面自动化

外壳和文件

剪贴板

演出

在开始时启动一次会话以解锁快速路径：

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

环境变量

当只有一个设备连接时，工具会自动检测到它。对于多个设备，传递 serial 显式或设置参数 ANDROID_SERIAL.

故障排除

adb devices 显示 unauthorized 接受设备上的RSA指纹提示。如果未出现提示，请在“开发人员选项”中撤销USB调试授权并重新连接。

start_session 失败 确保scrcpy已安装 scrcpy-server 二进制文件是可访问的。集 SCRCPY_SERVER_PATH 如果它位于非标准位置。

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

expand_notifications / expand_settings / collapse_panels 失败 这些工具需要一个活动的scrcpy会话。跑 start_session 第一。

剪贴板在Android 10上不起作用+ ADB剪贴板访问在Android 10+上受到限制。启动scrcpy会话——scrcpy剪贴板协议绕过了此限制。

多台设备已连接 通过 serial 每个工具或设置 ANDROID_SERIAL 环境变量。

安全

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

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

许可证

麻省理工学院——见 许可证