Electron Viewer

@acertijosapps/electron-viewer

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.

• Live video: Page.startScreencast from the Chrome DevTools Protocol (CDP) over WebSocket. It keeps streaming while the app window is covered or minimized.
• Real input: mouse move and hover, click, double click, right click, drag, wheel and full keyboard passthrough (including ⌘C/⌘V/⌘A on macOS, IME and dictation).
• Touch: a touch mode in the viewer turns the pointer into a finger, and the agent can tap, swipe, long press and pinch, for touch-first and kiosk apps.
• Every app and window: launch your project with electron . from the viewer, or attach to any app started with --remote-debugging-port. Apps on ports 9222–9231 are found automatically.
• Main process too: launched apps also expose their main process (Node inspector), so the agent can run code there, resize the real window and open DevTools.
• MCP server: the same actions as tools, plus JavaScript in the renderer and main process, the accessibility tree with click-ready coordinates, and console logs.
• Nothing to add to your app: no preload, no dependency, no code changes.

Requirements

• Node.js 18 or later.
• An Electron app. To launch it from the viewer, the project must have 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.
• Works on macOS, Linux and Windows.

Quick start

From your Electron project folder:

npx @acertijosapps/electron-viewer@1.1.1

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= .

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:

npx @acertijosapps/electron-viewer@1.1.1 --launch-cmd "yarn dev --remoteDebuggingPort {cdpPort} --inspect {inspectPort}"

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:

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

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.

electron-viewer [options]        Start the viewer

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

--project Project to launch with "electron ." (default: current folder) --launch-cmd Launch with this shell command instead; {cdpPort} and {inspectPort} are replaced with the debugging ports -p, --port Viewer port (default 8094, env PORT) --host Interface to bind (default 127.0.0.1, env HOST) --attach Attach at startup to an app on this CDP port --inspect With --attach: the app's main process inspector port --viewer-url Viewer the MCP talks to (default http://localhost:8094)

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).

Use it with an AI agent (MCP)

Claude Code:

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

Any other MCP client:

{

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

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/electron-viewer@1.1.1) 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.

In the Claude Code browser pane

Add the viewer to .claude/launch.json and open it with preview_start electron-viewer:

{

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

HTTP API

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.

Parameters are validated with the same limits as the MCP tools. A missing, unknown or out-of-range field gets a 400 that names it, e.g. {"error": "POST /api/swipe: missing x1, y1, x2, y2; unknown fromX, fromY, toX, toY (fields: window, x1, y1, x2, y2, ms)"}. Coordinates are normalized 0–1 and query string values are converted to numbers and booleans.

How it works

• Everything goes through CDP with 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.
• One screencast session per window, shared by every viewer tab and stopped when the last one closes. The last frame is kept for late joiners. Focus and page lifecycle are emulated while someone is watching, so a covered or minimized window keeps painting.
• Viewer input is queued in order and mouse moves are coalesced to one per animation frame. A hidden textarea holds the focus: keys are sent with 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.
• Touch goes through 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.
• Each process keeps one connection per window and per main process, which also collects console messages and exceptions (the last 1000 per app).
• For an app with no known inspector, each Node inspector on ports 9229–9238 is asked once, read only, whether it is Electron and which CDP port its app listens on. Any other Node process started with --inspect in that range gets one short connection (it logs Debugger attached.) and is left alone.
• Launched and attached apps are remembered in ~/.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.

Limitations

• CDP only sees web content. Native UI (title bar, menus, dialogs, tray, notifications) isn't shown or clickable; use evaluate_main to drive it from the main process. Capturing it would mean capturing the screen, and with it any