mcp-electron-driver
Supports interaction with CodeMirror editors and contenteditables through keyboard typing tools that simulate real per-character keydown events for accurate text input.
Provides tools for driving Electron applications from AI agents, enabling interaction with desktop apps through click, type, drag, screenshot, JavaScript evaluation, console log reading, multi-window handling, and accessibility snapshot capture.
Enables interaction with React-based Electron applications, including specialized drag handling with React fiber-prop access for splitter patterns and pointer event simulation.
Supports driving Svelte-based Electron applications through the same automation tools as other frameworks, including element selection, interaction, and state inspection.
electron-driver
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-driverYou 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-driverClaude 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 |
| A tool needs a running session, but there isn't one |
|
|
| An action hit its timeout |
| Selector or file didn't match |
| Path-based input points at a missing file |
| Arguments failed validation |
| Tool name not recognized |
| 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 // scopedSelector-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_fileandset_input_filesread 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
_electronnamespace 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_windowroutes 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_filedoes not populatefile.path. Apps usingwebUtils.getPathForFile()must useeval_mainwith 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
codefield.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
returnworks andawaitworks.argpayloads 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 serverThe 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 toolsaccessibility_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
Scored across 39 tools
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.
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.
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.
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
Related MCP Connectors
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server that gives any AI assistant eyes and hands on your desktop — screenshots, clicking, typing, OCR, window management, accessibility-tree queries, workflow recording.5Apache 2.0
- AlicenseNot gradedqualityBmaintenanceGives 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.142MIT
- AlicenseAqualityCmaintenanceCross-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.202MIT
- AlicenseBqualityBmaintenanceMCP server providing AI-friendly computer-use primitives (capture, detect, click) to let LLM agents drive desktop GUI applications on Windows, macOS, and Linux.232MIT