AI导哈

Android设备控制服务

一个通过AI代理实现对Android设备的实时视觉和控制的服务，提供屏幕流媒体、快速输入控制和UI自动化等功能。

  • by invidtiv
  • TypeScript
  • 本地部署
  • 17 星标
  • 更新于
在 GitHub 查看 invidtiv/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设备

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

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倍 比快照模式
  • 最适合实时控制和快速交互

性能比较

操作 快照模式 流模式
轻击 ~100-300ms ~5-10ms
滑动 ~300-500ms ~50-100ms
键入文本 ~50ms/字符 ~5ms总计
屏幕截图 ~500ms ~33ms（30fps）

工具参考（32个工具）

设备管理

工具 参数 说明
android.devices.list - 列出连接的设备
android.devices.info serial 获取设备信息（型号、SDK等）
android.adb.enableTcpip serial, port? 启用WiFi调试
android.adb.getDeviceIp serial 获取设备WiFi IP
android.adb.connectWifi ipAddress, port? 通过WiFi连接
android.adb.disconnectWifi ipAddress? 断开WiFi连接

视觉

工具 参数 说明
android.vision.startStream serial, maxSize?, maxFps?, frameFps? 启动连续流（实现快速输入）
android.vision.stopStream serial 停止流
android.vision.snapshot serial 拍摄PNG屏幕截图（无需流媒体）
android.ui.dump serial 获取UI层次结构XML
android.ui.findElement serial, text?, resourceId?, className?, contentDesc? 使用水龙头坐标查找元素

输入控制

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

工具 参数 说明
android.input.tap serial, x, y 点击坐标
android.input.swipe serial, x1, y1, x2, y2, durationMs? 滑动手势
android.input.longPress serial, x, y, durationMs? 长按
android.input.pinch serial, centerX, centerY, startDistance, endDistance, durationMs? 捏住变焦
android.input.dragDrop serial, startX, startY, endX, endY, durationMs? 拖放
android.input.text serial, text 键入文本
android.input.keyevent serial, keycode 发送密钥代码

应用程序控制

工具 参数 说明
android.app.start serial, packageName, activity? 启动应用程序
android.app.stop serial, packageName 强制停止应用程序
android.apps.list serial, system? 列出已安装的应用程序
android.activity.current serial 获取前台活动

系统

工具 参数 说明
android.shell.exec serial, command 执行shell命令
android.file.push serial, localPath, remotePath 将文件推送到设备
android.file.pull serial, remotePath, localPath 从设备中提取文件
android.file.list serial, path 列表目录
android.clipboard.get serial 获取剪贴板
android.clipboard.set serial, text 设置剪贴板
android.notifications.get serial 获取通知

屏幕控制

工具 参数 说明
android.screen.wake serial 唤醒屏幕
android.screen.sleep serial 睡眠屏幕
android.screen.isOn serial 检查屏幕是否打开
android.screen.unlock serial 解锁（仅不安全）

资源

服务器公开这些MCP资源：

  • android://devices -连接设备的JSON列表
  • android://device/<serial>/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" }

通用钥匙码

密钥 代码 密钥 代码
主页 3 返回 4
VOLUME_UP 24 VOLUME_DOWN 25
电源 26 输入 66
删除 67 选项卡 61
菜单 82 APP_SWITCH 187
唤醒 224 睡眠 223

故障排除

未找到设备

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代理集成指南。

许可证

麻省理工学院

相关 MCP