mcp-electron-driver

Launch an Electron app via Playwright. Must be called before any other driving tool. Pass the absolute path to the compiled main process entry (e.g. out/main/index.js). Wipes the screenshots directory on each fresh start. Detects the single-instance-lock failure mode and gives a helpful hint.

Close the running Electron app cleanly. Safe to call even if no app is running.

Get current window title, URL, viewport size (populated from window.innerWidth/innerHeight), uptime, and devicePixelRatio.

Return a structured text representation of the visible page with numbered refs. Each interactive or labelled element gets a [ref] number that can be passed to click, type, hover, get_text, and other tools instead of a selector — eliminating selector-guessing round-trips. Call this FIRST before interacting with a page to see what is on screen. The snapshot is an accessibility-tree-based representation similar to Playwright MCP's browser_snapshot.

Capture a full-page PNG of the current window. Returns the absolute path. Pass name to control the filename (without extension).

Delete all screenshots from the current session directory. Useful between test phases to keep storage tidy.

Click an element. Pass selector (Playwright selector) or ref (from a snapshot). Pass force: true to skip actionability checks when an overlay is in the way.

Fill a text input, REPLACING existing content. Pass selector or ref. Uses Playwright's fill. For keyboard-level typing (CodeMirror, contenteditables), use keyboard_type instead.

Type a literal string as real keyboard events. Unlike type (which uses fill), this dispatches per-character keydown/keypress/keyup events — works with CodeMirror, contenteditables, editors, and anything that listens to keydown. Optionally focus a selector first.

Press a keyboard key or chord in the window. Examples: "Escape", "Enter", "Control+S", "Shift+Tab", "Control+Shift+P".

Alias for keyboard_type with no focus selector. Types a literal string into the currently focused element as keyboard events. Kept for backwards compatibility.

Hover the mouse over an element. Pass selector or ref. Pass force: true to skip actionability checks when an overlay intercepts.

Drag from one point to another using real Chromium input events (via Playwright's CDP mouse pipeline). Because these are trusted browser events, they automatically generate matching PointerEvents — so React onPointerDown, native pointerdown listeners, setPointerCapture, CSS :hover/:active, and every other pointer consumer all see the drag exactly as they would from a real user. Coordinates are CSS pixels. Pass detectSelector to have the driver measure that element before and after the drag and include the movement delta in the result — the only reliable way to catch drags that silently hit a min/max clamp. If the primary strategy does not move the detect target (and a detectSelector was given), the driver automatically falls back to invoking the React handler directly via fiber-prop access and then dispatching move/up events on both document and window. Disable the fallback with fiberFallback: false. The result includes a strategy field indicating which path worked (pointer-capture or react-fiber).

Pause for N milliseconds. Prefer wait_for_selector or wait_for when possible.

Wait until an element matching a selector appears (or reaches a given state: attached/detached/visible/hidden). Returns element count and the bounding box of the first match so you do not need a follow-up eval. Honours timeoutMs (default 5000).

Poll a JavaScript predicate in the renderer until it returns truthy, then return its value. The predicate is a function body; use return to yield a value. Example body: return document.querySelectorAll(".item").length >= 3.

Fast check for whether any element matches, plus the count. Pass selector or ref. Does not wait.

Read an attribute from the first matching element. Pass selector or ref.

Read the current value of a form input, textarea, or select. Pass selector or ref.

Get the bounding box of the first matching element in CSS pixels. Pass selector or ref. Useful before drag operations.

Read computed CSS property values from the first element matching a selector. Returns { exists, styles } where styles is an object mapping each requested property to its computed value. Example properties: "background-color", "font-family", "display".

Enumerate elements matching a selector, returning basic info about each (tag, text snippet, id, key attributes, bounding box). Great for "what buttons are on this screen" or "give me all list items". Capped at 50 by default.

Return information about the currently focused element: tag, id, classes, text snippet, and bounding box. Returns { focused: false } if nothing meaningful has focus (document.body).

Clear the value of an input or textarea matching a selector. Equivalent to selecting all and deleting.

Select an option in a dropdown. Pass value (the option's value attribute), label (its visible text), or index (zero-based). At least one must be provided.

Check a checkbox or radio button matching a selector. No-op if already checked.

Uncheck a checkbox matching a selector. No-op if already unchecked.

Scroll an element (if selector is given) or the window (if not). Pass x/y for an absolute scroll position, or dx/dy for a delta from the current position. Use scroll_into_view instead if you just want to make an element visible.

Scroll the first element matching a selector into view if needed. Safe to call even if the element is already visible.

Set files on an without triggering the native file picker. This is the CORRECT way to test file upload UI in Electron — much more reliable than drop_file. Pass one or more absolute file paths.

Capture the accessibility tree of the current page as JSON. Useful for testing screen-reader behaviour, finding elements by role, or auditing for missing ARIA labels. Optionally pass interestingOnly: false to include every node, not just interesting ones.

List every BrowserWindow the app has open, with title, URL, id, and whether it is focused/minimized/maximized. For single-window apps this returns one entry.

Make a different BrowserWindow the "current" one that subsequent tools drive. Pass index (from windows_list) or titleMatch (substring of window title). The driver will focus the target window and route all future click/type/eval calls to it.

Install an auto-responder for JavaScript dialogs (alert/confirm/prompt/beforeunload). Once set, the next dialog(s) will be auto-accepted or dismissed without a human. Pass action: "accept" or "dismiss", optional text for prompts, and once: true to auto-uninstall after the first dialog (default true).

Read the text content of the first matching element. Pass selector or ref. Does not wait.

Evaluate JavaScript in the renderer (page) context. Pass a FUNCTION BODY — use return to yield a value. Example: return document.title. Supports async/await. Same contract as eval_main. Pass an arbitrary JSON-serializable arg to be available as the arg variable inside the body.

Evaluate JavaScript in the Electron main process. Pass a FUNCTION BODY — use return to yield a value. The body receives electron (the full Electron module) and arg (your JSON-serializable payload). Supports async/await. Use this to invoke IPC handlers, read paths, or drive windows the renderer cannot reach.

Return recent console messages captured since the app started. Includes renderer console (log/info/warn/error/debug) and main-process stdout/stderr. Pass clear: true to drain the buffer after reading.

Simulate dropping a file onto a target element by dispatching synthetic drag/drop events with a DataTransfer containing the file contents. Works for apps that read File via web APIs (FileReader, File.text, etc.). Does NOT populate file.path — apps that rely on webUtils.getPathForFile() or legacy file.path must use eval_main to invoke their IPC directly.