Android Viewer

@acertijosapps/android-viewer

适用于浏览器的 Android 模拟器实时查看器，并附带 MCP 服务，让 AI Agent 能够操控模拟器。 专为 AI 编码工具（例如 Claude Code）的浏览器窗格打造：你和 Agent 可以实时查看并操控同一个模拟器，包括折叠屏姿态。

• 实时视频：通过 WebSocket 传输 adb exec-out screenrecord（H.264），并在浏览器中使用 WebCodecs 解码。
• 输入操作：点击、拖动、长按和滚动都会转换为 adb shell input 命令。
• 机器上的所有 AVD：选择正在运行的模拟器，或从查看器启动已停止的模拟器。
• 模拟器控件：返回、主页、最近任务、电源、音量、旋转、全分辨率截图。
• 折叠屏：合上 / 半展开 / 展开 / 后置显示屏。在模拟器上，这些操作会改变模拟铰链状态，类似于模拟器自带的控件；折叠或旋转时，串流会跟随当前活动显示屏。
• MCP 服务：提供相同的操作作为工具，因此 Agent 的点击操作会实时显示在查看器中。
• 无需在设备上安装任何内容：无需 APK，也无需推送服务端；只需 adb。

要求

• Node.js 18 或更高版本。
• Android SDK platform tools（adb）；若要列出和启动 AVD，还需要 emulator。 通过 ANDROID_HOME、ANDROID_SDK_ROOT 或默认 SDK 位置查找；可使用 ADB 和 EMULATOR 覆盖。
• 支持 WebCodecs 的浏览器（基于 Chromium 的浏览器、Safari 16.4+、Firefox 130+）。
• 支持 macOS、Linux 和 Windows。

快速开始

npx @acertijosapps/android-viewer

打开 http://localhost:8093 并选择设备。深层链接：?avd=Pixel_10 或 ?serial=emulator-5554。

android-viewer [options]        Start the viewer
android-viewer mcp [options]    Start the MCP server on stdio

  -p, --port <port>      Viewer port (default 8093, env PORT)
      --host <host>      Interface to bind (default 127.0.0.1, env HOST)
      --viewer-url <url> Viewer the MCP talks to (default http://localhost:8093)

其他环境变量：MAX_DIM（编码视频最长边，默认值为 1024）、 BIT_RATE（默认值为 6M）、SCREENSHOT_MAX（MCP 截图最长边，默认值为 1024）和 DEBUG=1（记录每条输入命令）。

与 AI Agent 一起使用（MCP）

Claude Code：

claude mcp add android-viewer -- npx -y @acertijosapps/android-viewer mcp

其他 MCP 客户端：

{
  "mcpServers": {
    "android-viewer": {
      "command": "npx",
      "args": ["-y", "@acertijosapps/android-viewer", "mcp"]
    }
  }
}

也已列入官方 MCP Registry，条目为 io.github.acertijosapps/android-viewer。

保持查看器运行（npx @acertijosapps/android-viewer），即可查看 Agent 的操作。如果查看器未运行， MCP 会直接通过 adb 操控设备。

工具	功能
list_devices	机器上的 AVD（运行时包含 serial 和 booted）以及其他 adb 设备
launch_avd	按名称启动 AVD
get_state	显示屏尺寸、旋转角度、当前姿态、可用姿态和查看器 URL
screenshot	当前活动显示屏的 PNG 截图，最长边 ≤ 1024 px
tap	input tap
swipe	input swipe；起点和终点相同且时间 ≥ 500 ms 时表示长按
press_key	back、home、recents、power、wakeup、volup、voldown、enter、delete、tab、escape
type_text	input text（可打印的 ASCII 字符）
rotate	向左或向右旋转 90°（模拟器）
set_posture	closed、half_opened、opened、rear_display、状态 ID 或 reset；返回新状态

坐标在截图范围内归一化为 0–1（x = pixel_x / image_width），因此在任何姿态或方向下都适用。仅连接一台设备时，serial 为可选项。

在 Claude Code 浏览器窗格中

将查看器添加到 .claude/launch.json，并使用 preview_start android-viewer 打开：

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "android-viewer",
      "runtimeExecutable": "npx",
      "runtimeArgs": ["-y", "@acertijosapps/android-viewer"],
      "port": 8093,
      "autoPort": false
    }
  ]
}

HTTP API

MCP 使用查看器的 API；你也可以调用它。serial 放在查询字符串或请求正文中；只有一个设备时可省略。POST 请求需要 content-type: application/json 和本地来源，以防其他网站控制你的设备。

端点
GET /api/devices	[{ avd, serial, booted, model }]：serial: null = 已停止，booted: null = 未能及时响应
GET /api/state	显示尺寸、旋转、displayId、折叠状态和可用折叠状态
GET /api/screenshot?max=<px>	PNG；实际屏幕尺寸见 X-Screen-Width / X-Screen-Height
POST /api/tap	{ x, y }
POST /api/swipe	{ x1, y1, x2, y2, ms }
POST /api/key	{ key }
POST /api/text	{ text }
POST /api/posture	{ posture }
POST /api/rotate	{ direction: "left" | "right" }
POST /api/launch	{ avd }

当查看器标签页正在查看设备时，操作会通过其实时会话执行：查看器会立即更新；如果某个手势没有产生画面，监视程序会重启视频流。

工作原理

• 每台设备使用一个会话，由所有标签页共享；最后一个标签页关闭时，会话停止。
• 每秒读取一次 dumpsys display（尺寸、旋转，以及逻辑显示屏 0 对应的物理显示屏）和 cmd device_state state。显示屏发生变化时，会等待其稳定，然后使用新面板的 --display-id 重启 screenrecord：设备折叠时会切换面板。
• screenrecord 只在屏幕发生变化时输出帧，因此查看器会保留自上次 IDR 以来的 GOP，供稍后加入的用户使用；没有视频时则发送屏幕截图。
• 每台设备同时只运行一个 screenrecord：运行两个会耗尽模拟器的软件编码器（err=-38）。客户端请求的重启会受到频率限制。
• 屏幕截图使用原始 screencap（在模拟器内压缩 PNG 在高负载下很慢），通过面积平均缩小尺寸，再用 node:zlib 编码为 PNG，不需要原生依赖项。

限制

• 拖动操作会在松开时发送（以实际时长执行一次 input swipe），而不是实时发送。
• 暂不支持键盘直通和音频；请使用 type_text 和 press_key。
• 延迟高于 scrcpy 等原生客户端。
• 多台模拟器同时录制时，软件编码器会变慢；可用 RAM 较少时（模拟器被换出到交换分区），每次 adb shell 调用都可能耗时数秒。
• 如果应用请求自身的折叠状态（DeviceStateManager.requestState），应用处于前台时，该请求会优先于 set_posture。
• 采用 Flip_Horizontal_Fold 样式的 AVD 若只有一个物理显示屏，关闭时状态会改变，但画面保持不变。

为什么不用 ws-scrcpy？

我们最初尝试了 ws-scrcpy：视频流和输入都能正常工作，但折叠状态改变后视频会冻结，直到重新加载（其 scrcpy 1.19 服务端仍绑定到之前的显示屏），而且它没有折叠状态控制功能。

贡献

分支模型（main · beta）、Conventional Commits 和版本发布说明见 CONTRIBUTING.md；变更记录列于 CHANGELOG.md。

作者

由 AcertijosApps 制作。请访问 acertijosapps.com/librerias 查看我们的其他库。

问题或建议：[email protected]，或提交一个 issue。

许可证

MIT