io.github.acertijosapps由 GitHub 账号 acertijosapps 发布v1.1.0更新于 Nov 7, 2026
Drive Electron apps over CDP: screenshots, clicks, drags, keys, JS in renderer and main, logs.
通过 CDP 操控 Electron 桌面应用：截图、鼠标、触摸与键盘输入、在渲染进程和主进程执行 JavaScript，以及读取控制台日志。
Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。
参照 仓库 中的启动说明。
Live viewer for Electron apps in the browser, plus an MCP server so an AI agent can drive them. Built for the browser pane of AI coding tools (such as Claude Code): you and the agent watch and control the same app window, in real time.
[Electron Viewer showing the example app: window selector and launch button on top, the live window in the middle, and the reload, DevTools, window size, touch and screenshot controls at the bottom]Page.startScreencast from the Chrome DevTools Protocol (CDP) over WebSocket. It keeps
streaming while the app window is covered or minimized.electron . from the viewer, or attach to any app
started with --remote-debugging-port. Apps on ports 9222–9231 are found automatically.electron in its
node_modules (npm install --save-dev electron); if its binary hasn't been downloaded yet, the
viewer downloads it on the first launch.From your Electron project folder:
Open http://localhost:8094 and click Launch. The viewer runs electron . on free debugging
ports (CDP from 9222, Node inspector from 9229). Deep link to a window: ?window=<target id>.
If your app is started by another tool (electron-vite, Electron Forge, a custom script), give the viewer
your own start command. {cdpPort} and {inspectPort} are replaced with free debugging ports, and the
Launch button (and launch_app) runs it in the project folder:
That line is for electron-vite; for an npm script that ends in electron ., pass the flags after --:
--launch-cmd "npm start -- --remote-debugging-port={cdpPort} --inspect={inspectPort}". The command is
only read from the command line or ELECTRON_VIEWER_LAUNCH_CMD, never from the HTTP API or the MCP.
Or start the app yourself with the flags and the viewer finds it:
Apps on CDP ports 9222–9231 are found automatically, and so is their main process when its inspector is
on 9229–9238. --inspect is optional; without it you get everything except the main-process features
(evaluate_main, real window resizing and in-app DevTools). To attach on other ports, use the form in
the viewer or --attach and --inspect.
Other environment variables: MAX_DIM (longest side of the streamed frames, default 1920), QUALITY
(JPEG quality, default 80), SCREENSHOT_MAX (longest side of MCP screenshots, default 1024),
CDP_PORT / INSPECT_PORT (first ports to scan and launch on, default 9222 / 9229) and
ELECTRON_VIEWER_STATE_DIR (where launched and attached apps are remembered, default
~/.cache/electron-viewer).
Claude Code:
Any other MCP client:
Also listed in the official MCP Registry as
io.github.acertijosapps/electron-viewer.
The examples pin an exact version. The viewer and the MCP can run code in your app, so pin the version
you reviewed instead of letting npx fetch whatever was published last, and update it on purpose.
Keep the viewer running (npx @acertijosapps/[email protected]) to watch what the agent does. Without
it, the MCP drives the app over CDP directly. Apps launched by either one are visible to the other.
Coordinates are normalized to 0–1 over the content screenshot (x = pixel_x / image_width), so they
hold at any window size. window is optional when only one window is open; it takes the target id
from list_windows or part of the window title.
Add the viewer to .claude/launch.json and open it with preview_start electron-viewer:
The MCP uses the viewer's API; you can call it too. window (target id or part of the title) goes in
the query string or the body and is optional with a single window. The server only listens on
127.0.0.1, only accepts a local Host and origin, and POST requests require
content-type: application/json, so other websites can't drive your apps.
ws: no Playwright, no Puppeteer, nothing injected into the app.
The renderer is reached through --remote-debugging-port (one page target per window) and the
main process through the Node inspector (--inspect), where the console API provides require.Input.dispatchKeyEvent, and text that arrives without
key events (IME, dictation) with Input.insertText. On macOS, ⌘A, ⌘C, ⌘V, ⌘X and ⌘Z are sent as
editing commands, because the native menu that normally handles them never sees CDP events.Input.dispatchTouchEvent. The first touch action on a window also turns on touch
emulation (navigator.maxTouchPoints 5, pointer: coarse) until the viewer or MCP that sent it exits.--inspect in that range gets one short connection (it logs Debugger attached.) and is left alone.~/.cache/electron-viewer, so the viewer and the MCP see
the same apps. Launched apps write their output to a log file there and keep running if the viewer
or MCP exits.evaluate_main to drive it from the main process. Capturing it would mean capturing the
screen, and with it any other window on top of the app, so the viewer doesn't.dialog.showMessageBoxSync) block the main process: evaluate_main waits until
the dialog is closed.WebContentsView is a separate CDP target, so it is listed as its own window. <webview> tags are
not listed.touchstart themselves see it, but
Chromium on desktop doesn't turn it into a context menu. The viewer's touch mode is one finger; use
pinch for two.--launch-cmd must pass the ports on to Electron; how depends on the tool. Launched apps keep running
when the viewer exits; close them from the app (or its terminal).Branching model (main · beta), Conventional Commits and releases are described in
CONTRIBUTING.md; changes are listed in CHANGELOG.md. The
example app in example/ is there to try changes.
Made by AcertijosApps. See the rest of our libraries at acertijosapps.com/librerias.
Questions or proposals: [email protected] or open an issue.
MIT
来源：README.md，提交 980e6e6
List windows
Lists the running Electron apps (found on CDP ports 9222–9231, launched or attached) and their windows. main=true means the main process is reachable (evaluate_main, real window resizing). Includes the viewer URL to watch a window live in a browser pane.
无需输入参数。
Launch app
Starts the Electron project on free debugging ports, so both the renderer (CDP) and the main process (Node inspector) are reachable, and waits for the first window. It runs `electron .` with the project's own Electron, or the launch command configured with --launch-cmd (e.g. a dev server).
projectAttach to app
Attaches to an Electron app already running with --remote-debugging-port=<port> (and optionally --inspect=<inspect_port> for the main process). Apps on ports 9222–9231 are found without attaching.
port必填inspect_portScreenshot
Captures the window content (PNG). For click, drag, hover and scroll use normalized coordinates: x = pixel_x / image width, y = pixel_y / image height. Native UI (title bar, menus, dialogs) is not included.
windowClick
Clicks a point of the window content (Input.dispatchMouseEvent). count=2 is a double click.
x必填y必填countbuttonwindowmodifiersDrag
Presses the left button at one point, moves to another with intermediate steps and releases (a real drag).
x1必填x2必填y1必填y2必填windowmodifiersduration_msHover
Moves the mouse to a point without clicking (hover effects, tooltips).
x必填y必填windowTap
Taps a point with one finger (Input.dispatchTouchEvent): the page gets touch and pointer events with pointerType "touch". The first touch action turns on touch emulation for the window (maxTouchPoints, pointer: coarse).
x必填y必填windowSwipe
Swipes one finger from one point to another (touch events; use drag for the mouse). Scrolls touch lists and drives swipe gestures.
x1必填x2必填y1必填y2必填windowduration_msLong press
Holds one finger on a point and releases it. Apps that time touchstart themselves see a long press; Chromium on desktop doesn't turn it into a context menu.
x必填y必填windowduration_msPinch
Two-finger pinch centered on a point: scale > 1 spreads the fingers (zoom in), scale < 1 brings them together.
xyscale必填windowduration_msScroll
Scrolls with the mouse wheel at a point. Positive delta_y scrolls down; deltas are in CSS pixels.
xywindowdelta_xdelta_yType text
Types text into the focused element (Input.insertText; any Unicode). Click the field first; for Enter or shortcuts use press_key.
text必填windowPress key
Presses a key, optionally with modifiers (e.g. key "a" + ["meta"] selects all on macOS). Named keys: Enter, Tab, Backspace, Delete, Escape, Space, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, Insert, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12; or any single character.
key必填windowmodifiersResize window
Sets the size of the window content area in CSS px. With the main process it resizes the real window; if the window cannot reach that size (smaller screen, kiosk, full screen), without the main process or with emulate=true, the page viewport is emulated at the exact size instead. Width and height 0 restore the window size.
width必填height必填windowemulateReload
Reloads the page of the window (renderer only; the main process keeps running).
windowignore_cacheEvaluate in renderer
Evaluates a JavaScript expression in the window page (main world) and returns its JSON value. Promises are awaited.
windowexpression必填Evaluate in main process
Evaluates a JavaScript expression in the app's main process (Node inspector) and returns its JSON value. `require` is available, e.g. require('electron').BrowserWindow.getAllWindows().map(w => w.getTitle()). Promises are awaited. Needs main=true in list_windows.
appexpression必填Accessibility tree
Returns the accessibility tree of the window as indented text (role "name" value [state]). Interactive elements carry @(x, y): their center, normalized like click coordinates.
windowinteractive_onlyConsole logs
Console messages and uncaught exceptions of the app: renderer windows and main process (up to the last 1000). source "stdout" returns the raw output of an app started with launch_app.
applevellimitsourcewindow已满足适用检查项的 90%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
npx @acertijosapps/[email protected]npx @acertijosapps/[email protected] --launch-cmd "yarn dev --remoteDebuggingPort {cdpPort} --inspect {inspectPort}"electron --remote-debugging-port=9222 --inspect=9229 .electron-viewer [options] Start the viewerelectron-viewer mcp [options] Start the MCP server on stdio
--project <dir> Project to launch with "electron ." (default: current folder) --launch-cmd <cmd> Launch with this shell command instead; {cdpPort} and {inspectPort} are replaced with the debugging ports -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)claude mcp add electron-viewer -- npx -y @acertijosapps/[email protected] mcp{ "mcpServers": { "electron-viewer": { "command": "npx", "args": ["-y", "@acertijosapps/[email protected]", "mcp"] } }}{ "version": "0.0.1", "configurations": [ { "name": "electron-viewer", "runtimeExecutable": "npx", "runtimeArgs": ["-y", "@acertijosapps/[email protected]"], "port": 8094, "autoPort": false } ]}