MCP Scrcpy Vision

mcp scrcpy愿景

一 MCP服务器 这为AI代理提供了对Android设备的完全视觉和控制。

特征：

• 实时视觉：通过scrcpy H.264+ffmpeg进行连续屏幕流式传输
• 快速输入控制：流式传输时，输入使用scrcpy控制协议（~5-10ms延迟，而adb shell的延迟为~100-300ms）
• 用户界面自动化：通过带有点击坐标的uiautomator进行元素检测
• 完全输入控制：点击、滑动、长按、捏住、拖放、文本、按键代码
• 系统访问：Shell命令、文件传输、剪贴板、通知
• 多设备：同时控制多个Android设备
• WiFi ADB：无线连接，实现不受限制的自动化

______________________________________________________________________

快速开始

1.先决条件

必修的：

• Node.js 18+
• PATH中的ADB（Android平台工具）
• 启用USB调试的Android设备

对于流媒体（建议用于快速输入）：

• 屏幕镜像 -下载发布，解压 scrcpy-server 文件
• FFmpeg -安装并添加到PATH

2.安装

git clone https://github.com/anthropics/mcp-scrcpy-vision.git
cd mcp-scrcpy-vision
npm install
npm run build

3.配置

创建 .env 文件：

# Required for streaming + fast input
SCRCPY_SERVER_PATH="C:\scrcpy-win64-v3.2\scrcpy-server"
SCRCPY_SERVER_VERSION="3.2"

# Optional (defaults shown)
ADB_PATH="adb"
FFMPEG_PATH="ffmpeg"
DEFAULT_MAX_SIZE="1024"
DEFAULT_MAX_FPS="30"
DEFAULT_FRAME_FPS="2"

4.添加到MCP客户端

克劳德桌面 (%APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "android": {
      "command": "node",
      "args": ["C:/path/to/mcp-scrcpy-vision/dist/index.js"],
      "env": {
        "SCRCPY_SERVER_PATH": "C:/scrcpy/scrcpy-server",
        "SCRCPY_SERVER_VERSION": "3.2"
      }
    }
  }
}

光标 （设置>MCP）：

{
  "android": {
    "command": "node",
    "args": ["C:/path/to/mcp-scrcpy-vision/dist/index.js"],
    "env": {
      "SCRCPY_SERVER_PATH": "C:/scrcpy/scrcpy-server",
      "SCRCPY_SERVER_VERSION": "3.2"
    }
  }
}

5.连接设备

1. 在Android设备上启用USB调试（设置>开发人员选项>USB调试）
2. 通过USB连接
3. 在设备上接受RSA指纹提示
4. 验证： adb devices 应该显示您的设备

______________________________________________________________________

运作原理

两种操作模式

1.快照模式（无需流式传输）

• 用途 android.vision.snapshot 用于截图
• 输入使用ADB shell命令（每次操作约100-300ms）
• 无需scrcpy/ffmpeg即可工作
• 最适合简单的自动化或流媒体不可用时

2.流媒体模式（推荐）

• 开始 android.vision.startStream
• 通过资源URI提供连续JPEG帧
• 输入使用scrcpy控制协议（每个动作~5-10ms）
• 速度快10-20倍 比快照模式
• 最适合实时控制和快速交互

性能比较

______________________________________________________________________

工具参考（32个工具）

设备管理

视觉

输入控制

注： 这些在流式传输时自动使用快速scrcpy控制，否则将回退到ADB。

应用程序控制

系统

屏幕控制

______________________________________________________________________

资源

服务器公开这些MCP资源：

• android://devices -连接设备的JSON列表
• android://device//frame/latest.jpg -最新JPEG帧（流式传输时）

______________________________________________________________________

使用示例

基本自动化回路（流模式）

1. Start stream: android.vision.startStream { serial: "ABC123" }
2. Read resource: android://device/ABC123/frame/latest.jpg
3. AI analyzes image, decides to tap "Login" button
4. Find element: android.ui.findElement { serial: "ABC123", text: "Login" }
5. Tap at returned coordinates: android.input.tap { serial: "ABC123", x: 540, y: 1200 }
6. Wait 500ms, read resource again, repeat
7. When done: android.vision.stopStream { serial: "ABC123" }

简单截图模式

1. Take screenshot: android.vision.snapshot { serial: "ABC123" }
2. AI analyzes image
3. Find and tap: android.ui.findElement + android.input.tap
4. Take another screenshot to verify

WiFi连接工作流程

1. Connect device via USB
2. android.adb.enableTcpip { serial: "ABC123" }
3. android.adb.getDeviceIp { serial: "ABC123" } → "192.168.1.50"
4. Disconnect USB cable
5. android.adb.connectWifi { ipAddress: "192.168.1.50" }
6. Now use "192.168.1.50:5555" as serial for all commands

应用程序测试示例

1. android.app.start { serial: "ABC123", packageName: "com.example.app" }
2. android.vision.startStream { serial: "ABC123" }
3. Wait for app to load, read frame
4. android.ui.findElement { serial: "ABC123", resourceId: "username_field" }
5. android.input.tap { serial: "ABC123", x: 540, y: 300 }
6. android.input.text { serial: "ABC123", text: "testuser@example.com" }
7. android.input.keyevent { serial: "ABC123", keycode: 66 }  // Enter
8. Read frame, verify login succeeded
9. android.vision.stopStream { serial: "ABC123" }

______________________________________________________________________

通用钥匙码

______________________________________________________________________

故障排除

未找到设备

adb kill-server
adb start-server
adb devices

确保已启用USB调试并接受RSA指纹。

Scrcpy版本不匹配

SCRCPY_SERVER_VERSION 必须与scrcpy服务器文件完全匹配。检查您下载的scrcpy发布版本。

未找到ffmpeg

• 视窗：从下载https://ffmpeg.org/download.html，提取，将bin文件夹添加到PATH
• macOS: brew install ffmpeg
• Linux: apt install ffmpeg 或 yum install ffmpeg

或设置 FFMPEG_PATH 在.env中添加完整路径。

uiautomator转储失败

某些设备需要打开屏幕。请尝试 android.screen.wake 第一。

剪贴板无法工作（Android 10+）

Android 10+限制剪贴板访问。使用UI自动化进行粘贴。

流无法启动

1. 检查scrcpy服务器路径是否正确
2. 验证版本号是否匹配
3. 首先尝试独立运行scrcpy以验证其是否正常工作

______________________________________________________________________

注意事项和限制

• 流媒体播放时输入速度快：当流处于活动状态时，点击/滑动/文本/按键事件使用scrcpy控制协议（~5-10ms延迟）。没有流媒体，回落到 adb shell input （约100-300ms）。
• 每个设备一个流 一次
• 快照无需scrcpy即可工作 -不需要流媒体时的有用回退
• 剪贴板 在Android 10上有平台限制+
• 通知 可能需要在较新的Android上获得权限
• 捏手势 目前模拟单指；真正的多点触控需要流媒体会话

______________________________________________________________________

安全警告

此MCP服务器提供 完全控制 通过连接的Android设备：

• 执行任意shell命令
• 在设备上读/写文件
• 控制UI和输入
• 访问剪贴板和通知

仅连接您拥有并信任AI代理的设备。

______________________________________________________________________

发展

npm run dev     # Development with tsx
npm run build   # Compile TypeScript
npm start       # Run production build

看 claude.md 用于开发人员文档。 看 特工.md 用于AI代理集成指南。

______________________________________________________________________

许可证

麻省理工学院