Skip to main content
Glama

electron-driver

npm version license node version

Drive Electron apps from AI agents. Click, type, drag, screenshot, evaluate JavaScript in the renderer or main process, read console logs, handle multi-window apps, capture accessibility snapshots — all through an MCP (Model Context Protocol) server that plugs into Claude Code, Claude Desktop, Cursor, and any other MCP-compatible agent host.

https://github.com/user-attachments/assets/a95500d2-28d2-4ee1-9965-8f7e1ef54caa

Built on Playwright's experimental _electron API. Works with any Electron app — React, Vue, Svelte, vanilla — as long as you can point it at a compiled main-process entry.

Status: v0.3.0. First public release. 38 tools covering real workflows.

Why this exists

AI agents can reason about what a desktop app should do, but they can't see or interact with one on their own. Web browsers have plenty of agent-automation options; Electron has almost none. This package closes that gap: give an agent the path to your compiled Electron app and it can drive it the same way a human would.

Common use cases:

  • An agent verifies a feature it just implemented by actually running the app and checking the visible result

  • Visual regression testing during a refactor

  • Accessibility audits via ARIA tree snapshots

  • Reproducing bugs from a natural-language description

  • Teaching a subagent to iterate on UI until a spec passes

Related MCP server: native-devtools-mcp

Install

Requires Node 18+ and an Electron app you've already built.

npm install electron-driver

You don't need to install Playwright browsers separately — _electron drives your Electron binary directly.

Register with your agent host

Claude Code (project scope)

Create .mcp.json at the repo root:

{
  "mcpServers": {
    "electron-driver": {
      "command": "npx",
      "args": ["electron-driver"]
    }
  }
}

Claude Code (user scope — available in every project)

claude mcp add electron-driver --scope user -- npx electron-driver

Claude Desktop / Cursor / other

Add to the host's MCP configuration, pointing at npx electron-driver or the absolute path to node_modules/electron-driver/index.mjs.

Core idea

The server owns exactly one Electron session at a time. start_app launches it, everything else drives it, stop_app closes it. Screenshots go to a session directory that is wiped on every start_app — no pileup, no stale artefacts. All tool calls are logged to <project>/.electron-driver/driver.log during a session.

Errors carry a stable code field so callers can branch programmatically without regex-matching prose:

Code

Meaning

NOT_RUNNING

A tool needs a running session, but there isn't one

ALREADY_RUNNING

start_app called while a session exists

TIMEOUT

An action hit its timeout

NOT_FOUND

Selector or file didn't match

FILE_NOT_FOUND

Path-based input points at a missing file

BAD_ARGUMENT

Arguments failed validation

UNKNOWN_TOOL

Tool name not recognized

ERROR

Everything else

Tools

All 38 tools grouped by purpose. Every selector-based tool uses Playwright's full selector engine: CSS, text=, role=, [aria-label=], :has-text(), scoping (main >> button), etc.

Lifecycle

start_app — launch the app. Takes main (absolute path to the compiled main entry), optional cwd, args, env, screenshotsDir, timeoutMs. Returns { title, url, viewport, screenshotsDir, logFile }. Detects the single-instance-lock failure mode and gives a helpful hint instead of a raw disconnection error.

stop_app — close cleanly. Safe on an already-stopped session.

info — { title, url, viewport: {width, height, devicePixelRatio}, uptimeMs }. Viewport is populated from window.innerWidth/innerHeight.

Capturing

screenshot — full-page PNG. Pass name (without extension) to control the filename. Returns { path }.

cleanup_screenshots — wipe the current session's screenshot directory.

console_logs — recent renderer console messages (log/info/warn/error/ debug/pageerror) and main-process stdout/stderr. Rolling 1000-entry buffer. Filter by source (renderer/main/all), type, and limit. Pass clear: true to drain after reading.

Interaction

click — click an element. Options: timeoutMs, button (left/right/middle), clickCount, force (skip actionability checks), position (click at an offset inside the element).

type — fill a text input, replacing existing content. Fast but only works on real inputs. For editors/CodeMirror/contenteditables, use keyboard_type.

keyboard_type — type as real per-character keydown events. Pass focusSelector to click an element first. Warns in the result if nothing has focus and no focus selector was passed.

press — press a key or chord: "Escape", "Enter", "Control+S", "Shift+Tab", "Control+Shift+P".

press_sequence — alias for keyboard_type with no focus selector.

hover — hover over an element. Options: timeoutMs, force.

drag — drag from one point to another using real Chromium input events (via Playwright's CDP mouse pipeline). Because these are trusted browser events, Chromium's pointer pipeline generates matching PointerEvents as a side effect, so React onPointerDown, native pointerdown listeners, setPointerCapture, CSS :hover/:active, and every other pointer consumer see the drag exactly as if a real user had performed it. Coordinates are CSS pixels. Pass detectSelector and the driver will measure the element before and after the drag and include detect.moved in the result — the only reliable way to catch drags that silently hit a min/max clamp.

{
  "from": { "x": 275, "y": 400 },
  "to":   { "x": 420, "y": 400 },
  "detectSelector": ".sidebar-resize-handle"
}

If the primary strategy does not move the detect target, the driver automatically falls back to invoking the React handler directly via fiber-prop access and dispatching move/up events on both document and window — covering all known React splitter patterns. Disable the fallback with fiberFallback: false. The result includes strategy ("pointer-capture" or "react-fiber").

clear_input — empty an input or textarea.

select_option — select from a <select> by value, label, or index.

check — check a checkbox or radio. Options: timeoutMs, force.

uncheck — uncheck a checkbox.

scroll — scroll a container (pass selector) or the window. Supports absolute (x, y) or delta (dx, dy).

scroll_into_view — ensure an element is visible. Safe if already is.

drop_file — simulate dropping a file onto a target via synthetic DragEvents and a reconstructed File with DataTransfer. Works for apps that read the File via web APIs (FileReader, File.text(), etc). Does not populate file.path — apps relying on webUtils.getPathForFile() must use eval_main to invoke their own IPC handler directly.

set_input_files — the correct way to test file upload UI. Sets files on an <input type="file"> without a native dialog. Much more reliable than drop_file when the app uses real file inputs.

Waiting

wait — fixed pause in milliseconds. Prefer the others.

wait_for_selector — wait until a selector reaches a state (attached/detached/visible/hidden). Honours timeoutMs. Returns count, box, and elapsedMs on success; the error carries elapsed vs requested on timeout.

wait_for — poll a JavaScript predicate (function body, use return) until it returns truthy. Options: timeoutMs, pollMs.

Checking & reading state

exists — { exists, count } fast check, no waiting. Accepts the full selector engine.

get_text — text content of the first match. Accepts the full selector engine. Returns { exists, text }.

get_attribute — read an HTML attribute by name. Returns { exists, value }.

get_value — read an input/textarea/select's current value.

get_bbox — bounding box as { x, y, width, height } in CSS pixels. Use before dragging or clicking at an offset.

get_computed_style — read one or more computed CSS properties. Pass a properties array.

elements_list — enumerate elements matching a selector with their tag, id, classes, text snippet, box, and key attributes. Great for "what buttons exist on this screen". Capped at 50 by default; tune via limit.

focused_element — what currently has focus, with tag/id/classes/text and bounding box. Returns { focused: false } if nothing meaningful has focus.

accessibility_snapshot — capture the ARIA tree as JSON. Useful for a11y audits and finding elements by role. Pass interestingOnly: false to include every node. Pass root to snapshot a subtree.

Multi-window

windows_list — every BrowserWindow the app has open, with id, title, URL, focus/visibility/state flags.

switch_window — route subsequent tool calls to a different window. Pass index or titleMatch.

Dialogs

dialog_handler — install an auto-responder for JavaScript dialogs (alert/confirm/prompt/beforeunload). Pass action: "accept" | "dismiss", optional text for prompt(), and once: true (default) to auto-uninstall after the first dialog.

Evaluation escape hatches

Both eval_renderer and eval_main use the same contract: pass a function body, use return to yield a value, supports async/await, and an optional arg payload is available as the local arg variable.

eval_renderer — evaluate in the renderer (page) context.

{
  "js": "return document.querySelectorAll(arg.selector).length",
  "arg": { "selector": ".item" }
}

eval_main — evaluate in the Electron main process. The body receives electron (the full Electron module) and arg.

{
  "js": "return electron.app.getName()"
}
{
  "js": "const w = electron.BrowserWindow.getAllWindows()[0]; w.webContents.send('open-file', arg.path); return true",
  "arg": { "path": "C:/docs/README.md" }
}

Use eval_main as the escape hatch for everything the DOM side can't reach: invoking IPC handlers, reading user paths, driving secondary windows, bypassing native dialogs for apps that use them.

Selectors cheat sheet

text=Open File              // exact text match
text=/^Save$/               // regex
[aria-label="Settings"]     // ARIA attribute
role=button[name="Close"]   // ARIA role
button:has-text("Save")     // CSS with text predicate
button.primary              // plain CSS
main >> text=Save           // scoped

Selector-engine consistency

Every selector-based tool (click, hover, wait_for_selector, get_text, get_attribute, get_value, get_bbox, exists, elements_list, scroll_into_view, select_option, check, uncheck, set_input_files) goes through Playwright's full locator engine. Anything Playwright accepts, these tools accept — including text=, role=, and :has-text().

Tools that read low-level DOM via eval_renderer under the hood (get_computed_style, scroll, focused_element, drop_file) use native document.querySelector and only support CSS. This is documented on each tool's description where relevant.

Troubleshooting

"Electron process exited immediately after launch." Another copy of your app is already running and grabbed the single-instance lock — the second process quits via app.requestSingleInstanceLock(). Close the running instance (check your taskbar and background processes) and retry.

drag returned ok:true but detect.moved is false. The most common cause is a min/max clamp on the target (e.g. a resizable sidebar at its MAX_WIDTH). Try dragging in the opposite direction to confirm the drag pipeline is working. If it's really not the clamp, the React fiber fallback should catch it automatically — check the strategy field in the result. If even that returns moved:false, use eval_renderer or eval_main to invoke the app's own drag API directly.

type throws "Element is not an <input>..." You're hitting a button, a div, or a contenteditable. Use keyboard_type with a focusSelector instead.

click times out on an element that's clearly there. Something is covering it — a modal backdrop, a tooltip, a toast. Use exists first to confirm the count, then try force: true, or use eval_renderer to check getComputedStyle(el).pointerEvents.

Native dialogs are invisible. Playwright cannot see OS-level file pickers, save dialogs, or system alerts. Use eval_main to invoke the same IPC handler your UI button uses. For JavaScript dialogs (alert/confirm/prompt), use dialog_handler to auto-respond.

Development build vs compiled app. This drives the built app, not dev-server output. Run your build command before start_app, and rebuild

  • restart the session after source changes.

One session at a time. Calling start_app while a session is running returns ALREADY_RUNNING. Call stop_app first.

Logs. Every tool call is logged to <project>/.electron-driver/driver.log while a session is active. Useful when debugging why an agent got stuck.

Screenshots location. Defaults to <project>/.electron-driver/screenshots, where <project> is the nearest directory containing .git or package.json. Override via screenshotsDir on start_app.

Security

This server gives the connected agent full control over an Electron app, including arbitrary code execution in the main process (via eval_main). The Electron main process has unrestricted Node.js access — filesystem, network, child processes, everything. This is by design: it's what makes the driver powerful enough to drive real apps.

What this means for you:

  • Only use over stdio (the default). Never expose this server over HTTP, WebSocket, or any network transport. Stdio ties it to the process that spawned it — your local Claude Code or Claude Desktop session.

  • Trust the agent. The agent calling these tools can do anything on your machine via eval_main. Only connect agents you trust.

  • Don't use in multi-tenant environments. This is a single-user, local-machine tool. It's not designed for shared servers, CI pipelines with untrusted input, or any context where the caller might be adversarial.

  • drop_file and set_input_files read local files and pass their contents to the renderer. The file paths should come from trusted sources.

If you're running this with Claude Code, the risk profile is the same as giving Claude Code terminal access (which you already have). The driver doesn't add new capabilities beyond what eval in a terminal could do — it just makes them convenient for the agent to use.

Known limitations

  • Playwright's _electron namespace is officially experimental upstream. Occasional launch timeouts on slow machines; usually retrying fixes it.

  • Developed primarily on Windows. Mac and Linux should work — Playwright handles them — but are less battle-tested. Bug reports welcome.

  • switch_window routes subsequent calls to the selected window, but the console-log buffer is populated from the initial window. Multi-window console capture is a planned v0.4 item.

  • drop_file does not populate file.path. Apps using webUtils.getPathForFile() must use eval_main with their own IPC.

  • No built-in network-request capture yet — planned for v0.4.

Implementation notes

For anyone curious or contributing:

  • Single Electron session, owned by the MCP server process.

  • Screenshots wiped on every start_app — intentional.

  • Console logs captured into a rolling 1000-entry buffer.

  • Every tool call is logged; errors carry a stable code field.

  • Error messages are rewritten to be attributed to the driver tool, not the underlying Playwright method.

  • Single-instance-lock detection keys on "process disconnected within 5s of launch", which is the actual shape of the failure.

  • Evals are async-IIFE wrapped, so return works and await works.

  • arg payloads are coerced server-side (JSON-parse on strings) to protect against MCP clients that stringify arg fields.

  • stderr is used for status messages; stdout is reserved for MCP protocol frames.

Contributing

Issues and PRs welcome. Run locally with:

cd electron-driver
npm install
node index.mjs  # stdio MCP server

The server logs a ready banner to stderr and waits for MCP frames on stdin. Test it against a real Electron app via any MCP client.

License

MIT

Available Tools

39 tools
accessibility_snapshotA

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.

Inputs: interestingOnly, root.

checkA

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

Inputs: selector (required), timeoutMs, force.

cleanup_screenshotsA

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

Inputs: no named parameters.

clear_inputB

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

Inputs: selector (required), timeoutMs.

clickA

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.

Inputs: selector (required), ref, timeoutMs, button, +3 more.

console_logsA

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.

Inputs: limit, source, type, clear.

dialog_handlerA

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

Inputs: action, text, once.

dragA

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

Inputs: from (required), to (required), steps, detectSelector, +1 more.

drop_fileA

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.

Inputs: filePath (required), selector, mimeType.

elements_listA

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.

Inputs: selector (required), limit, attributes.

eval_mainA

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.

Inputs: js (required), arg.

eval_rendererA

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.

Inputs: js (required), arg.

existsA

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

Inputs: selector, ref.

focused_elementA

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

Inputs: no named parameters.

get_attributeB

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

Inputs: name (required), selector, ref.

get_bboxB

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

Inputs: selector, ref.

get_computed_styleA

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

Inputs: selector (required), properties (required).

get_textA

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

Inputs: selector, ref, trim.

get_valueC

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

Inputs: selector, ref.

hoverA

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

Inputs: selector (required), ref, timeoutMs, force.

infoA

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

Inputs: no named parameters.

keyboard_typeA

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.

Inputs: text (required), focusSelector, delayMs, timeoutMs.

pressB

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

Inputs: key (required).

press_sequenceA

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

Inputs: text (required), delayMs.

screenshotA

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

Inputs: name, fullPage.

scrollA

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.

Inputs: selector, x, y, dx, +1 more.

scroll_into_viewA

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

Inputs: selector (required), timeoutMs.

select_optionA

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.

Inputs: selector (required), value, label, index, +1 more.

set_input_filesA

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.

Inputs: selector (required), files (required), timeoutMs.

snapshotA

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.

Inputs: selector.

start_appA

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.

Inputs: main (required), cwd, args, screenshotsDir, +3 more.

stop_appA

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

Inputs: no named parameters.

switch_windowA

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.

Inputs: index, titleMatch.

typeA

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.

Inputs: text (required), selector, ref, timeoutMs.

uncheckA

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

Inputs: selector (required), timeoutMs, force.

waitA

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

Inputs: ms (required).

wait_forA

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.

Inputs: js (required), timeoutMs, pollMs.

wait_for_selectorA

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

Inputs: selector (required), state, timeoutMs.

windows_listA

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.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 39 tools

    Disambiguation4/5

    Most tools have distinct purposes, but some overlap exists, such as keyboard_type and press_sequence being aliases, and drag having a complex fallback that could confuse its boundary with other interaction tools. However, descriptions are detailed enough to clarify differences.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures, such as click, get_text, wait_for_selector, and accessibility_snapshot. There are no deviations in naming conventions.

    Tool Count3/5

    With 39 tools, the count is high for an Electron driver, bordering on heavy. While it covers many scenarios, it may overwhelm agents with its breadth, suggesting some tools could be consolidated or omitted for better focus.

    Completeness5/5

    The toolset provides comprehensive coverage for Electron app testing, including app lifecycle (start_app, stop_app), window management, UI interaction, evaluation, waiting, and debugging. No obvious gaps are present; it supports full CRUD-like operations for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that gives any AI assistant eyes and hands on your desktop — screenshots, clicking, typing, OCR, window management, accessibility-tree queries, workflow recording.
      5
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives AI agents and MCP clients direct control over native desktop apps, Chrome/Electron browsers, and Android devices with screenshots, OCR, accessibility-based element lookup, input simulation, window management, CDP, and ADB in one local server.
      142
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Cross-platform desktop automation MCP server that lets AI agents capture screenshots, run OCR with UI-element classification, control mouse/keyboard, and launch programs on Linux, macOS, and Windows.
      20
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      MCP server providing AI-friendly computer-use primitives (capture, detect, click) to let LLM agents drive desktop GUI applications on Windows, macOS, and Linux.
      23
      2
      MIT