Electron Viewer

@acertijosapps/electron-viewer

在浏览器中实时查看 Electron 应用，并提供 MCP 服务，让 AI Agent 可以操控这些应用。 专为 AI 编码工具（例如 Claude Code）的浏览器窗格打造：你和 Agent 可以实时观看并 操控同一个应用窗口。

• 实时视频：通过 WebSocket 使用 Chrome DevTools Protocol (CDP) 中的 Page.startScreencast。即使应用窗口被遮挡或最小化，也会持续 推流。
• 真实输入：鼠标移动和悬停、单击、双击、右键单击、拖动、滚轮，以及完整的键盘输入 透传（包括 macOS 上的 ⌘C/⌘V/⌘A、输入法和听写）。
• 所有应用和窗口：在查看器中使用 electron . 启动项目，或连接到任何使用 --remote-debugging-port 启动的应用。 会自动发现使用 9222–9231 端口的应用。
• 主进程也能操作：启动的应用还会公开其主进程（Node 检查器），因此 Agent 可以在其中运行代码、调整真实窗口大小、打开 DevTools 并捕获原生边框。
• 原生边框捕获：捕获窗口上方的标题栏、上下文菜单和对话框。
• MCP 服务：提供相同的操作作为工具，还支持在渲染进程和主进程中运行 JavaScript、查看带有可点击坐标的无障碍树，以及查看控制台日志。
• 无需向应用添加任何内容：不需要 preload、依赖或代码更改。

要求

• Node.js 18 或更高版本。
• 一个 Electron 应用。若要从查看器启动，项目的 node_modules 中必须包含 electron（npm install --save-dev electron）；如果尚未下载其二进制文件，查看器会在首次启动时下载。
• 支持 macOS、Linux 和 Windows。

快速开始

在 Electron 项目目录中运行：

npx @acertijosapps/electron-viewer

打开 http://localhost:8094 并点击 Launch。查看器会在空闲调试端口上运行 electron .（CDP 从 9222 开始，Node 检查器从 9229 开始）。使用 ?window=<target id> 深度链接到某个窗口。

如果应用由其他工具（Electron Forge、electron-vite、自定义脚本）启动，请自行传入这些标志，查看器便会找到它：

electron --remote-debugging-port=9222 --inspect=9229 .

--inspect 是可选的；不使用它时，除主进程功能（evaluate_main、边框捕获、调整真实窗口大小和应用内 DevTools）外，其他功能均可使用。若要连接到其他端口，请使用查看器中的表单或 --attach。

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

      --project <dir>      Project to launch with "electron ." (default: current folder)
  -p, --port <port>        Viewer port (default 8094, env PORT)
      --host <host>        Interface to bind (default 127.0.0.1, env HOST)
      --attach <port>      Attach at startup to an app on this CDP port
      --inspect <port>     With --attach: the app's main process inspector port
      --viewer-url <url>   Viewer the MCP talks to (default http://localhost:8094)

其他环境变量：MAX_DIM（流式传输帧的最长边，默认值为 1920）、QUALITY （JPEG 质量，默认值为 80）、SCREENSHOT_MAX（MCP 截图的最长边，默认值为 1024）、 CDP_PORT / INSPECT_PORT（扫描和启动时使用的起始端口，默认值为 9222 / 9229）以及 ELECTRON_VIEWER_STATE_DIR（记住已启动和已连接应用的位置，默认值为 ~/.cache/electron-viewer）。

将其与 AI Agent 搭配使用（MCP）

Claude Code：

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

其他任何 MCP 客户端：

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

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

保持查看器运行（npx @acertijosapps/electron-viewer），即可观察 Agent 的操作。不运行查看器时，MCP 会通过 CDP 直接驱动应用。由其中任一方启动的应用，对另一方也可见。

工具	功能
list_windows	正在运行的应用（主进程可访问时会显示 main）及其窗口
launch_app	在项目中通过空闲的调试端口运行 electron .，并等待第一个窗口
attach	连接到 CDP 端口上的应用；也可选择指定其检查器端口
screenshot	窗口内容的 PNG 截图，最长边 ≤ 1024 px；frame: true 会添加原生窗口边框、菜单和对话框
click	左键、右键或中键单击；count: 2 表示双击；可选修饰键
drag	按下、分步移动并释放：执行真实拖动
hover	移动鼠标，但不单击
scroll	在某个位置滚动鼠标滚轮，增量以 CSS px 为单位
type_text	在聚焦的元素中输入文本（支持任意 Unicode）
press_key	输入 Enter、Tab、Escape、方向键、F1–F12……或任意字符，并可使用修饰键
resize_window	调整内容区域大小（有主进程时调整实际窗口；没有时则模拟调整）
reload	重新加载窗口页面
evaluate	在窗口页面中运行 JavaScript 并返回值
evaluate_main	在主进程中运行 JavaScript，可使用 require('electron')
get_accessibility_tree	获取角色、名称、值和状态；交互元素会附带归一化中心坐标
get_console_logs	获取渲染器窗口和主进程的控制台消息及异常，或原始 stdout

坐标在内容截图范围内归一化为 0–1（x = pixel_x / image_width），因此适用于任意窗口大小。仅打开一个窗口时，window 为可选参数；它会从 list_windows 获取目标 ID，或使用窗口标题的一部分。

在 Claude Code 浏览器窗格中

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

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

原生窗口边框捕获

frame 按钮（以及设置 frame: true 的 screenshot）会通过 desktopCapturer 从主进程捕获窗口所在的屏幕区域：标题栏、原生上下文菜单和窗口上方显示的对话框都会出现在截图中，每秒可捕获数帧。遮挡窗口的其他内容也会出现在截图中，但不包括屏幕顶部的 macOS 菜单栏。在边框模式下，仍可单击内容区域；无法通过查看器单击标题栏和原生菜单。

在 macOS 上，应用需要获得屏幕录制权限（系统设置 › 隐私与安全性 › 屏幕与系统音频录制）。对于通过 electron . 运行的应用，所需权限对应项目 node_modules/electron/dist 中的 Electron.app；错误消息会给出确切路径。允许权限后，重启应用。

HTTP API

MCP 使用查看器的 API；你也可以调用它。window（目标 ID 或标题的一部分）放在查询字符串或请求正文中；只有一个窗口时可省略。服务仅监听 127.0.0.1，只接受本地 Host 和来源，并且 POST 请求必须使用 content-type: application/json，因此其他网站无法操作你的应用。

端点
GET /api/windows	[{ id, name, cdpPort, inspectPort, main, windows: [{ id, title, url }] }]
GET /api/project	查看器启动的项目，以及是否安装了 Electron
GET /api/screenshot?max=<px>&frame=1	PNG；视口尺寸位于 X-Viewport-Width / X-Viewport-Height
GET /api/ax-tree?interactiveOnly=true	{ tree }
GET /api/logs?level=&source=&limit=	{ logs } 或 { stdout }
POST /api/launch	{ project? }
POST /api/attach	{ port, inspectPort? }
POST /api/click	{ x, y, button?, count?, modifiers? }
POST /api/drag	{ x1, y1, x2, y2, ms? }
POST /api/hover	{ x, y }
POST /api/scroll	{ x, y, dx, dy }
POST /api/text	{ text }
POST /api/key	{ key, modifiers? }
POST /api/resize	{ width, height }（0 × 0 可恢复窗口尺寸）
POST /api/reload	{ ignoreCache? }
POST /api/evaluate	{ expression }
POST /api/evaluate-main	{ expression, app? }
POST /api/devtools	切换 DevTools；没有主进程时返回 DevTools url

工作原理

• 所有操作都通过 CDP 和 ws 完成：不使用 Playwright、Puppeteer，也不会向应用注入任何内容。渲染进程通过 --remote-debugging-port 访问（每个窗口对应一个 page 目标），主进程则通过 Node 检查器（--inspect）访问，其控制台 API 提供了 require。
• 每个窗口使用一个屏幕捕获会话，由所有查看器标签页共享，并在最后一个标签页关闭时停止。最后一帧会保留，供稍后加入的用户查看。有人正在观看时，会模拟焦点和页面生命周期，因此被遮挡或最小化的窗口仍会绘制画面。
• 查看器输入会按顺序排队，鼠标移动会合并为每个动画帧最多一次。一个隐藏的文本区域用于保持焦点：按键通过 Input.dispatchKeyEvent 发送，没有按键事件的文本输入（IME、听写）则通过 Input.insertText 发送。在 macOS 上，⌘A、⌘C、⌘V、⌘X 和 ⌘Z 会作为编辑命令发送，因为通常处理这些操作的原生菜单无法收到 CDP 事件。
• 每个进程会为每个窗口和每个主进程各保持一个连接，同时收集控制台消息和异常（每个应用最多保留最近 1000 条）。
• 已启动和已连接的应用会记录在 ~/.cache/electron-viewer 中，因此查看器和 MCP 会看到相同的应用。已启动的应用会将输出写入该目录中的日志文件，并且即使查看器或 MCP 退出也会继续运行。

限制

• CDP 只能查看 Web 内容。原生 UI（标题栏、菜单、对话框、托盘、通知）仅在帧模式下可见，无法点击；请使用 evaluate_main 从主进程驱动它。
• 同步对话框（dialog.showMessageBoxSync）会阻塞主进程：evaluate_main 和帧捕获会一直等待，直到对话框关闭。
• 每个 WebContentsView 都是独立的 CDP 目标，因此会作为单独的窗口列出。<webview> 标签不会列出。
• 无音频。
• 帧模式每秒运行几帧，并且在 macOS 上需要屏幕录制权限。
• 在启动前需要先构建的应用（Forge、electron-vite）无法从查看器启动；请使用调试标志启动它们，它们会自动被检测到。

参与贡献

分支模型（main · beta）、Conventional Commits 和发布流程见 CONTRIBUTING.md；变更记录见 CHANGELOG.md。example/ 中的示例应用可用于试验更改。

作者

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

如有疑问或建议，请联系 [email protected]，或提交问题。

许可证

MIT