Electron Stagewright
Electron Stagewright is an MCP server for driving and testing real Electron apps through accessibility-oriented automation, assertions, diagnostics, and session management.
Launch an Electron app, attach to a running CDP endpoint, or inject into a running process; stop, detach, or force-kill sessions.
Snapshot renderer accessibility trees in full, diff, compact-text, capped, or subtree form; find elements semantically by role, name, and state.
List and switch windows and renderer surfaces; reload and resize windows.
Read element state, text, value, attributes, bounding box, computed styles, and the focused element.
Interact by ref or selector: click, hover, drag, scroll, check/uncheck, select dropdown options, set/drop files, type text, send keys/chords/sequences, and type into code editors.
Wait for DOM events, selector states, and element states; assert text, value, URL, count, state, and text/attribute patterns with retrying expectations.
Capture screenshots, read console logs, handle native dialogs, and inspect app/runtime/environment status.
Optionally load plugins for accessibility audits, visual baselines, traces, IPC/network/storage/clock control, native menus/trays/notifications, and packaged-app validation; arbitrary JS eval is available only when explicitly enabled.
Allows AI agents to control real Electron desktop applications: launch apps, inspect the accessibility tree, click, type, select elements, read state, take screenshots, handle dialogs, and assert UI state using stable refs or selectors.
Electron Stagewright
Agentic UX testing for real Electron apps. Cue the app, prove the experience, and return bounded evidence through MCP.
Electron Stagewright is a Model Context Protocol (MCP) server that lets Claude Code, Codex, Cursor, Cline, Aider, and any MCP-compatible agent operate real Electron applications. Launch or attach, inspect the accessibility tree, interact through stable refs, assert behavior with retrying expectations, and capture diagnostics without turning every check into another agent round-trip.
Why this exists
Browser automation already has mature agent tooling. Electron adds a different boundary: the main process, renderer surfaces, native menus and dialogs, multiple windows, packaged runtimes, and signed release artifacts. A browser API exposed through MCP does not cover that whole product.
Electron Stagewright is designed agent-first from the primitive level up:
Errors carry hints, suggested next actions, and similar-ref alternatives — agents recover without an extra round-trip asking for context.
Every response reports its own token cost — agents budget in real time, not after the fact.
get_statereturns the full state envelope in one call — visible, enabled, checked, focused, disabled, aria-expanded, aria-busy, aria-invalid. No 4-call chain to decide if a button is clickable.wait_for_stateaccepts composite predicates —{ visible: true, enabled: true, focused: false }evaluated atomically by the server. One call replaces three.Snapshots flag
recently_changedelements — agents focus reasoning on what differs from the last view instead of reprocessing the whole tree.Snapshot diffs are a parameter, not a separate tool —
electron_snapshot({ since: 'last' })returns only deltas. Fewer APIs to remember.Compact text encoding on demand —
electron_snapshot({ format: 'text' })renders one line per element ([3] textbox "Email" value="" focused) with only non-default state, cutting snapshot tokens 5-10x versus the JSON shape when the agent just needs to look.expect_*primitives replace read-compare-retry chains —electron_expect_text({ ref, equals: 'Welcome', timeoutMs: 5000 })is one call, not five.electron_findqueries the accessibility tree semantically —{ role: 'button', name_contains: 'Submit', visible: true }— no CSS selectors, no XPath, no guessing.Hot-reload-aware — snapshot and find responses report when the renderer reloaded since the previous baseline, so agents know refs may need refreshing.
Framework-agnostic snapshot — built on accessibility roles and ARIA instead of framework-internal properties. Current fixtures cover vanilla, React, Vue, and Angular; the broader renderer matrix is still expanding.
Related MCP server: mcp-electron-driver
Electron-deep workflows
The server treats three Electron-specific workflows as first-class:
Attach to a running dev server without restarting it.
electron_attachconnects to apps exposing a loopback CDP endpoint, andelectron_injectcan attach to a running main process via the Node Inspector handshake when no debug flag was arranged up front.Session traces with deterministic replay and per-tool token budgets. Inspired by Playwright's
trace.zipbut designed for LLM agent sessions: a timeline of tool calls, arguments, results, timings, and token estimates — replayable against a fresh app instance, with budgets so agents can cap runaway loops.End-to-end validation of signed, notarized, packaged
.appbundles —codesign, Gatekeeper assessment, autoUpdater feed inspection, URL-scheme declaration checks, and crash reporter machinery. The full production surface, not just dev.
Microsoft's official Playwright MCP team explicitly declined to support Electron ("you can release your own server for Electron" — Pavel Feldman, lead). This project takes the invitation seriously.
Quick start
Requires Node.js 24 or newer (node -v); on Linux the server also needs a display (DISPLAY,
WAYLAND_DISPLAY, or xvfb-run -a). The default launch transport uses Playwright and an
Electron runtime. For a private setup in the current project, keep the server local to that project
and pin the release-tested package set.
Before configuring an MCP host, prepare the same package set once in a terminal. Electron downloads
its binary the first time something loads it, not during install, and that download prints a
progress line to stdout; inside an MCP session the line would land in the protocol stream. Fetch the
binary with Electron's install-electron bin, then run doctor, which reports "ok": true and
exits 0 when every required check passes:
npx -y --prefix ~/ --package @electron-stagewright/core@0.8.1 \
--package playwright@1.63.0 --package electron@42.11.10 install-electron
npx -y --prefix ~/ --package @electron-stagewright/core@0.8.1 \
--package playwright@1.63.0 --package electron@42.11.10 electron-stagewright doctor --jsonclaude mcp add electron-stagewright -- \
npx -y --prefix ~/ --package @electron-stagewright/core@0.8.1 \
--package playwright@1.63.0 --package electron@42.11.10 \
electron-stagewright --tool-profile essentialclaude mcp list should then show the server as connected (or run /mcp inside a session), and
its tools appear as mcp__electron-stagewright__electron_launch and so on. Keep the --package
list identical across all three commands: npx caches each list separately, so adding the demo or
a plugin package means running install-electron and doctor again with the new list. Keep
--prefix ~/ too: without it, npx skips any listed package the current project already has at
that version (an Electron app often has both Playwright and Electron), and the server, which runs
from npx's cache, cannot load it. The server still runs in the current directory. To move to
a newer release later, follow
Update to a new release.
The default Claude Code scope is local: it is available only in the current project and stays out
of unrelated workspaces. To share a reviewed configuration with a team, use --scope project,
which writes the same mcpServers shape to .mcp.json. See the
Claude Code MCP scopes for the host-specific behavior.
To verify a host before pointing it at your app, add the pinned
@electron-stagewright/demo@0.1.0 package and use the demo guide. The demo
is opt-in, so a normal core installation neither loads nor depends on it.
For local development, build the checkout and point your MCP host at the built CLI:
pnpm install
pnpm build
claude mcp add electron-stagewright -- \
node /abs/path/to/electron-stagewright/packages/core/dist/cli.jsShared project .mcp.json shape:
{
"mcpServers": {
"electron-stagewright": {
"command": "npx",
"args": [
"-y",
"--prefix",
"~/",
"--package",
"@electron-stagewright/core@0.8.1",
"--package",
"playwright@1.63.0",
"--package",
"electron@42.11.10",
"electron-stagewright",
"--tool-profile",
"essential"
]
}
}
}Then from any MCP-compatible agent (tool names as Claude Code shows them; other hosts prefix them differently):
// Launch
mcp__electron-stagewright__electron_launch({
main: "/abs/path/to/.vite/build/main.js",
env: { MY_ENV_VAR: "value" }
})
// Inspect with full state per ref
mcp__electron-stagewright__electron_snapshot()
// → [1] button "Open File" enabled=true visible=true
// [2] button "Settings" enabled=true visible=true
// [3] textbox "Email" value="" focused=false
// [4] heading "Welcome"
// Interact by ref
mcp__electron-stagewright__electron_click({ ref: 2 })
// Wait for a composite state in one call
mcp__electron-stagewright__electron_wait_for_state({
ref: 3, state: { focused: true, enabled: true }, timeoutMs: 2000
})
// Assert + retry in one call instead of read-compare-retry chain
mcp__electron-stagewright__electron_expect_text({ ref: 4, equals: "Welcome back" })
// Stop
mcp__electron-stagewright__electron_stop()The full tool list — every tool, its parameters, and operation type — is in
TOOL-REFERENCE.md, generated from the live dispatcher manifest
(pnpm docs:tools).
Documentation
Getting started — from a clean checkout to a complete driven session against the bundled example app.
Try the packaged demo — verify a published MCP host setup against a local, multi-window Electron task board without supplying your own app path.
Connect your MCP client — wire the published package into Claude Code, Codex, Claude Desktop, Cursor, VS Code, opencode, or any MCP host, confirm it connected, update it, or remove it.
Launch, attach, or inject — getting a session against YOUR app, including apps that are already running.
Assert UI state — refs vs selectors, the
expect_*family, waits, and snapshot diffs.Type into code editors — the reliable Monaco / EditContext typing path,
replace, the auto-pairing caveat, and how to verify the text landed.Capture diagnostics — screenshots, console, dialogs, and session traces.
Load, configure, and diagnose plugins — explicitly load plugins, grant their narrowest gates, and inspect enabled tools and safe config with
electron_plugins.Migrate from electron-driver — tool-by-tool mapping and the conceptual shifts.
Choose an Electron MCP server — compare Electron automation workflows by capability, trust boundary, recovery evidence, and your own app.
Compatibility — see which Node, Electron, operating-system, and transport combinations are verified by unit tests or real-runtime CI.
Concepts — the agent-native model and why the server is shaped the way it is: the response envelope, refs, snapshots, retrying assertions, sessions, and the eval/plugin trust model, each linked to the decision that set it.
Security model — the trust model, the controls behind
--allow-eval, and a deployment checklist.Guides index · TOOL-REFERENCE.md · Architecture Decision Records.
Server flags
Pass these after the CLI path in your MCP host config (the args array). All default to the safe
option; diagnostics go to stderr (stdout is reserved for the JSON-RPC protocol channel).
Flag | Effect |
| Register the |
| Confine host paths to within |
| Default directory |
| Per-dispatch backstop timeout (ms); a handler that never settles resolves as a retryable |
| Select the core tool surface: |
| Resolve an installed |
| Run preflight checks without starting MCP stdio: Node, Playwright, Electron, Linux display, configured paths, eval policy, project runtime alignment, and the exact serve configuration. Pass the same plugin/config/profile/timeout/demo flags you plan to serve with; doctor imports and briefly sets up only those explicitly trusted plugins, validates the complete server object graph, then tears it down. JSON mode includes bounded runtime/configuration facts and exits non-zero when a required check fails. Run it as |
| Validate a packaged macOS |
| Load a plugin by package name, first-party short name, or file path. Repeatable; a single value may be comma-separated. e.g. |
| Supply a plugin's config as inline JSON, validated against its schema. Keyed by plugin name; invalid input reports its Zod field path and correction input. |
The server exits 0 after a clean shutdown (SIGINT, SIGTERM, or the host closing stdin), 1 when
startup or shutdown teardown fails, and 2 for invalid usage such as an unknown flag.
Security defaults worth knowing when wiring this into another project: arbitrary JS (the
--allow-eval policy) and host-path launches (--app-root) are opt-in; electron_launch refuses
runtime-altering env vars (ELECTRON_RUN_AS_NODE, NODE_OPTIONS, LD_*, DYLD_*); and
user-supplied regex / text / key arguments are length- and complexity-bounded so a hostile tool call
cannot wedge the server.
Use --tool-profile essential when an agent needs the common launch, snapshot, interaction, wait,
and assertion workflow with a smaller initial manifest. Choose testing for the broader interaction,
read, and screenshot-evidence surface, or debug for attach, discovery, window, console, screenshot,
and dialog work.
full stays the default until the profile benchmark demonstrates equivalent task success with a
material context saving. See ADR-021 for the
measured budget policy.
What each response looks like (the agent-UX detail)
Success, for example from electron_expect_text:
{
"ok": true,
"session_id": "pw-...",
"matched": true,
"actual": "Welcome back",
"_meta": {
"estimated_tokens": 24,
"elapsed_ms": 142,
"session_id": "pw-...",
},
}Error:
{
"ok": false,
"error": "ref 7 not found in current snapshot",
"code": "REF_NOT_FOUND",
"hint": "The DOM may have rerendered since the last snapshot.",
"next_actions": ["electron_snapshot()", "electron_find({ role: \"button\" })"],
"similar_refs": [
{ "ref": 9, "role": "button", "name": "Submit" },
{ "ref": 12, "role": "button", "name": "Cancel" },
],
"retryable": false,
"http": 404,
"_meta": { "estimated_tokens": 89, "elapsed_ms": 23 },
}The agent has everything to decide its next move without asking for context.
Architecture
Three transport implementations behind a single ITransport interface, so the project survives if Playwright's experimental _electron API changes or gets deprecated:
PlaywrightElectronTransport—_electron.launch(), fast path (default).CDPTransport— Chrome DevTools Protocol direct, no Playwright dependency; launches packaged executables through a managed loopback endpoint or attaches to an existing one, with iframe, webview andWebContentsViewsurface targeting plus snapshot/find, eval, observe, and interaction on the selected surface.InjectorTransport— Node Inspector handshake into a running process; supports main-process eval, window discovery, and console capture when an app was not started with a CDP endpoint.
Plugin model: a small core, with domain capabilities shipped as separate @electron-stagewright/plugin-* packages loaded explicitly via --plugin (the core never auto-scans). Shipped today: plugin-a11y (surface-scoped axe-core audits with bounded violations and incomplete checks; a fixed engine, not agent JavaScript, so no --allow-eval grant), plugin-visual (BrowserWindow visual baselines with explicit update confirmation, environment metadata, confined artifact roots, and actual/diff evidence), plugin-trace (session trace + deterministic replay + per-tool token budget), plugin-ipc (capture / invoke / stub Electron IPC, gated behind main eval: --allow-eval=main, or bare --allow-eval), plugin-production (validate packaged macOS, Windows, and Linux artifacts through MCP, a public library API, or a CI JSON CLI: bundle integrity, update/crash machinery, macOS signing/notarization/Gatekeeper, Windows Authenticode, and AppImage embedded signatures), plugin-network (renderer request/response capture, bodies, and stubbing via the transport seam), plugin-clock (deterministic renderer virtual time via the Playwright clock seam), plugin-storage (read, seed, and assert cookies, storage snapshots and per-key localStorage / sessionStorage through the no-eval transport seam, and IndexedDB records through a renderer-eval gate; cookie values are redacted by default, IndexedDB values can be redacted with config), and plugin-native-ui (read, assert, and invoke the application menu — the macOS menu bar — capture the notifications the app shows including startup ones, and read system-tray state plus fire tray events via launch-time instrumentation, all via the transport native-UI seam, no eval).
Dogfooding targets
The MCP is built against two real Electron applications maintained by the author, covering distinct verticals so the design doesn't accidentally bias to one shape:
Code-editor shape — a code editor with runtime sandboxes, licensing, and IPC-heavy state. Stresses keyboard-driven flows, editor state, and license verification.
POS shape — a multi-tenant Point of Sale desktop app with embedded Fastify server and SQLite. Stresses forms, large tables, embedded backend, auto-updater feeds.
If your Electron app has a shape these don't cover, open an issue — we'd love to add it as an example fixture.
Security
The server is a privileged local tool, not a sandbox: it drives a real app and, under an eval opt-in (--allow-eval or a target-specific variant), runs arbitrary JavaScript inside it, so only a trusted agent host should invoke it. The security model covers the trust boundaries, the controls (eval opt-in + blocklist, channel allowlists, launch confinement, structured redaction), and a deployment checklist; the posture is recorded in ADR-014. To report a vulnerability, see SECURITY.md.
Contributing
This project is in its earliest days. Issues and discussions welcome. See CONTRIBUTING.md for the workflow, and GOVERNANCE.md for how the project is run and the path to becoming a co-maintainer.
Selecting test projects
pnpm test and pnpm test:coverage select the ordinary unit project, retained across
all six OS/Node CI cells. pnpm test:real selects the serialized real-electron project
and checks actual JSON results against scripts/real-test-inventory.json (25 reviewed files,
36 scenarios). It refuses missing binaries/required native-addon fixture inputs and rejects
missing, skipped or zero execution on every platform. Prepare the native-addon inputs with
node scripts/prepare-native-addon-fixture.mjs and export the variables it prints (on Windows it
also fetches Electron's node.lib and points at npm's bundled node-gyp, which needs MSVC).
Packed CLI qualification stays separate.
License
MIT — see LICENSE.
Available Tools
57 toolselectron_assert_patternAssert a text or attribute patternARead-only
Validate, in a single check (no polling), that an element's text or a named attribute matches a pattern. Target by ref or selector. With attribute set, reads that attribute; otherwise reads the element's trimmed text. Provide exactly one of: equals, contains, matches_regex. Optional flags (any of i, m, s, u) apply to matches_regex; g and y are rejected as stateful. Returns: { ok, session_id, matched, actual }. Errors: EXPECTATION_FAILED (element found but its value did not match the pattern — details carry expected + actual; a missing attribute reads as actual: null), SELECTOR_NO_MATCH (no element matched — this is one-shot, so a missing element is a precondition failure, not a retry; carries similar_refs), REF_NOT_FOUND (stale ref), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (no/multiple predicates, invalid regex or flags, or ref+selector both/neither).
Inputs: ref, flags, equals, contains, +4 more.
electron_attachAttach to running Electron appA
Attach to an already-running Electron app exposing a CDP debug endpoint (use electron_discover_running to find one, or start the app with --remote-debugging-port). Provide port (+ optional loopback host) or a loopback cdpUrl; pid alone is not attachable over CDP but, when supplied alongside, lets stop escalate to SIGKILL. The CDP transport supports eval/read/observe and core interaction surfaces against the attached app. The selected CDP page is also the default snapshot/find surface; explicit iframe/webview surface targeting remains unavailable. Returns: { ok, session_id, transport, windows, capabilities }. Errors: TRANSPORT_UNSUPPORTED (no attach-capable transport), CDP_DISCONNECTED (endpoint unreachable; a dropped session reconnects on its next call; retryable), CDP_TIMEOUT (handshake/method timeout; retryable), BAD_ARGUMENT (missing target selector or non-loopback endpoint).
Inputs: pid, host, port, cdpUrl, +1 more.
electron_checkCheck a checkbox or radioA
Check the checkbox/radio identified by ref or selector (no-op if already checked). Options: force, timeoutMs. Returns: { ok, session_id, target, checked: true }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: ref, force, selector, sessionId, +1 more.
electron_clear_inputClear an inputA
Clear the value of the input/textarea identified by ref or selector (sets it to empty). Options: force, timeoutMs. Returns: { ok, session_id, target, cleared }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: ref, force, selector, sessionId, +1 more.
electron_clickClick an elementA
Click the element identified by ref (from a snapshot) or selector. Options: button (left|right|middle, default left), clickCount (2 = double-click), force (bypass actionability), timeoutMs. Returns: { ok, session_id, target }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (no such element — re-snapshot; not retryable, carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED (not retryable), POINTER_NOT_DELIVERED (the click landed on another element or frame; retryable), NOT_RUNNING, BAD_ARGUMENT (ref+selector both/neither).
Inputs: ref, force, button, selector, +3 more.
electron_console_logsRead console logsARead-only
Read the captured renderer console output for the session, newest-relevant entries last. Filters (all optional, ANDed): type (one or more of log/info/warning/error/debug/...), match (a regular expression the text must match), since (epoch ms — only entries at/after it), limit (max entries, default 200, max 1000 — the most recent are kept). Returns: { ok, session_id, entries: [{ type, text, timestamp, windowId?, location? }], count, overflowed }. overflowed is the number of older entries the buffer dropped. Errors: NOT_RUNNING, BAD_ARGUMENT (invalid regex, or multiple sessions).
Inputs: type, limit, match, since, +1 more.
electron_detachDetach from Electron appA
Disconnect from an attached or injected app without stopping it. A launch-owned session cannot detach because its transport owns the process; this includes Playwright development launches and packaged CDP launches. Use electron_stop for that case. Returns: { ok, session_id, detached: true }. Errors: TRANSPORT_UNSUPPORTED (launch-owned session; not retryable), NOT_RUNNING (no such session), BAD_ARGUMENT (multiple sessions).
Inputs: sessionId.
electron_dialog_handlerHandle native dialogsA
Arm the auto-responder for native JS dialogs (alert/confirm/prompt/beforeunload) and read which dialogs fired. Dialogs block the renderer, so the policy is applied automatically the instant one appears. Arming args (all optional): action (accept|dismiss — the default for every dialog), perType (per-kind overrides, e.g. {"confirm":"accept","beforeunload":"dismiss"}, falls back to action), promptText (text submitted to prompt() when it is accepted), oneShot (apply to exactly the next dialog, then revert to dismiss). With NO arming args the call is inspect-only and leaves the policy unchanged. Read args (all optional): type (one or more kinds to include), since (epoch ms), limit (max events, default 50, max 200 — most recent kept), clear (flush the whole buffer after reading). Until armed, the default policy is dismiss, so dialogs never hang the app. Returns: { ok, session_id, policy, entries: [{ type, message, action, defaultValue?, promptText?, timestamp, windowId? }], count, overflowed }. overflowed counts dropped events across the whole buffer, not just the returned (type/since/limit-filtered) subset. Errors: NOT_RUNNING, BAD_ARGUMENT (promptText without an accepting prompt policy, or oneShot without a policy to arm).
Inputs: type, clear, limit, since, +5 more.
electron_discover_runningDiscover running Electron appsARead-only
Scan the conventional CDP debug ports (9222-9225 by default) for already-running, debuggable Electron apps on loopback only. No session required. Returns: { ok, targets, count, scanned } where each target is { targetId, port, appName, pid } and scanned reports { host, ports, elapsed_ms } so an empty result is unambiguous. Errors: BAD_ARGUMENT (non-loopback host, invalid port list, or timeout outside bounds). A failed probe is simply "no target on that port".
Inputs: host, ports, timeoutMs.
electron_doctorDiagnose Electron Stagewright environmentARead-only
Run non-mutating preflight checks without starting an Electron session: Node version, Playwright, Electron, Linux display, configured app root and screenshot directory, eval policy, and project Electron runtime alignment. Returns: { ok, doctor_ok, checks, runtime }, where runtime includes server and, with --app-root, target Electron/Node/V8/ABI facts plus a bounded native-addon inventory. Inspect failed checks and warnings before electron_launch. Errors: none.
Inputs: no named parameters.
electron_dragDrag one element onto anotherA
Drag the source element (ref or selector) onto the target element (targetRef or targetSelector), using the real mouse API. Options: force, timeoutMs. Returns: { ok, session_id, source, target }. Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), POINTER_NOT_DELIVERED (retryable), NOT_RUNNING, BAD_ARGUMENT (a side missing or both ref+selector given).
Inputs: ref, force, selector, sessionId, +3 more.
electron_drop_fileDrop files onto an elementA
Simulate dropping OS files onto the element identified by ref or selector. Web DataTransfer mode: reads each path on the host running the server, rebuilds the files in the renderer, and dispatches dragenter/dragover/drop with a real DataTransfer — engaging standard web drop handlers. Paths must be ABSOLUTE (max 10 files, 5242880 bytes each). default_prevented reports whether a drop handler engaged (called preventDefault); false usually means the target has no web drop handler. Apps that resolve dropped files to native OS paths need an app-specific IPC convention this tool does not simulate. Options: mimeType, timeoutMs. Returns: { ok, session_id, target, files, default_prevented }. Errors: ABSOLUTE_PATH_REQUIRED, FILE_NOT_FOUND, BAD_ARGUMENT (too many/large files, or ref+selector both), SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), NOT_RUNNING.
Inputs: paths (required), ref, mimeType, selector, +2 more.
electron_elements_listList elements matching a selectorARead-only
Return every element matching a CSS selector as { ref, role, name, bbox }, capped at limit (default 50, max 200). When more matched than returned, truncated is the number dropped and count is the true total. Returns: { ok, session_id, matches, count, truncated }. Errors: TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, limit, or multiple sessions).
Inputs: selector (required), limit, sessionId.
electron_existsCheck whether an element existsARead-only
Return whether the element identified by ref or selector is present in the DOM. A no-match is a normal result (exists: false), NOT an error — so an agent can poll for appearance/disappearance. Returns: { ok, session_id, exists }. Errors: TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector or ref+selector both/neither).
Inputs: ref, selector, sessionId.
electron_expect_countExpect a match countARead-only
Assert how many elements match, polling until the count satisfies the predicate or timeoutMs elapses. Target EITHER by selector (counts querySelectorAll; visible:true counts visible only, visible:false counts hidden only) OR by accessibility role/name filters (role, name_contains, name_exact, visible, enabled, interactive). Provide at least one of equals, min, max. Returns: { ok, session_id, matched, actual }. Errors: EXPECTATION_FAILED (count predicate not met within timeoutMs — details carry expected + actual; retryable), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (no count predicate, or selector mixed with role filters).
Inputs: max, min, role, equals, +8 more.
electron_expect_stateExpect an element stateARead-only
Assert the element identified by ref or selector matches the given state flags (any of visible, enabled, disabled, checked, selected, expanded, pressed, focused, readonly, required, invalid, busy), evaluated atomically and polled until they hold or timeoutMs elapses. Returns: { ok, session_id, matched, state }. Errors: EXPECTATION_FAILED (state not reached within timeoutMs — details carry expected + the last observed actual state; retryable), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, no state flags, or ref+selector both/neither).
Inputs: state (required), ref, selector, sessionId, +1 more.
electron_expect_textExpect element textARead-only
Assert the text of the element identified by ref or selector matches a predicate, polling until it holds or timeoutMs elapses. Provide exactly one of: equals, contains, regex, not_equals, not_contains. Optional flags (any of i, m, s, u) apply to regex; g and y are rejected as stateful. Returns: { ok, session_id, matched, actual }. Errors: EXPECTATION_FAILED (predicate not met within timeoutMs — details carry expected + actual; retryable), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (no/multiple predicates, invalid regex or flags, or ref+selector both/neither).
Inputs: ref, flags, regex, equals, +6 more.
electron_expect_urlExpect the window URLARead-only
Assert the active window's URL (location.href) satisfies a predicate, polling until it does or timeoutMs elapses. Provide exactly one of: contains (substring) or matches (JavaScript regex). Optional flags (any of i, m, s, u) apply to matches; g and y are rejected as stateful. Returns: { ok, session_id, matched, actual }. Errors: EXPECTATION_FAILED (URL did not match within timeoutMs — details carry expected + actual; retryable), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (no/both predicates, or invalid regex or flags).
Inputs: flags, matches, contains, sessionId, +1 more.
electron_expect_valueExpect form control valueARead-only
Assert the value of the element identified by ref or selector matches a predicate, polling until it holds or timeoutMs elapses. Provide exactly one of: equals, contains, regex, not_equals, not_contains. Optional flags (any of i, m, s, u) apply to regex; g and y are rejected as stateful. Returns: { ok, session_id, matched, actual }. Errors: EXPECTATION_FAILED (predicate not met within timeoutMs — details carry expected + actual; retryable), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (no/multiple predicates, invalid regex or flags, or ref+selector both/neither).
Inputs: ref, flags, regex, equals, +6 more.
electron_expect_visibleExpect an element visibleARead-only
Assert the element identified by ref or selector is visible, polling until it is or timeoutMs elapses. Visible means attached, laid out, and not visibility:hidden. Returns: { ok, session_id, matched }. Errors: EXPECTATION_FAILED (not visible within timeoutMs; retryable), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, or ref+selector both/neither).
Inputs: ref, selector, sessionId, timeoutMs.
electron_findFind elements by role and nameARead-only
Find elements in the renderer by accessibility role + name + state — no CSS selectors. Filters: role (exact), name_contains, name_exact, visible, enabled, interactive; limit caps the matches returned (count still reports the true total). Returns: { ok, surface_id, matches: [{ ref, role, name, bbox }], count, truncated, renderer_reloaded }. A ref may be null for non-interactive landmarks. On zero matches, hints may explain why: similar_names, without_state_filters, other_roles, roles_present, text_matches (text content, not accessible name, with a selector for electron_get_text / electron_exists) and next_actions. Errors: NOT_RUNNING (no session — call electron_launch first; not retryable), BAD_ARGUMENT (multiple sessions live — pass sessionId).
Inputs: role, limit, enabled, visible, +4 more.
electron_focused_elementGet the focused elementARead-only
Return the element that currently has focus as { ref, role, name }, or focused: null when nothing (or only the body) is focused. Useful after a Tab press or to confirm focus moved. Returns: { ok, session_id, focused }. Errors: TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (multiple sessions).
Inputs: sessionId.
electron_force_killForce-kill Electron appADestructive
Forcefully kill a session (SIGKILL) and release it — the escape hatch when stop hangs. Pass sessionId to target a specific session. Returns: { ok, session_id, killed: true }. Errors: NOT_RUNNING (no such session; not retryable), BAD_ARGUMENT (multiple sessions live — pass sessionId).
Inputs: sessionId.
electron_get_attributeGet an element attributeARead-only
Return the value of attribute name on the element identified by ref or selector (null when the attribute is absent — that is not an error). Returns: { ok, session_id, value }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: name (required), ref, selector, sessionId.
electron_get_bboxGet an element’s bounding boxARead-only
Return the bounding box (CSS pixels) of the element identified by ref or selector. Returns: { ok, session_id, bbox: { x, y, w, h } }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: ref, selector, sessionId.
electron_get_computed_styleGet computed CSS propertiesARead-only
Return the computed value of each requested CSS property (kebab-case, e.g. "background-color") for the element identified by ref or selector (max 50 properties). Only the requested properties are returned, never the full declaration. Returns: { ok, session_id, style: { : } }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: properties (required), ref, selector, sessionId.
electron_get_stateGet an element’s full stateARead-only
Return the full state envelope of the element identified by ref or selector: { visible, enabled, disabled, checked, selected, expanded, pressed, focused, readonly, required, invalid, busy } plus its role and name. One call answers "is this clickable / checked / focused". Returns: { ok, session_id, ref, role, name, state }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector or ref+selector both/neither).
Inputs: ref, selector, sessionId.
electron_get_textGet an element’s textARead-only
Return the text of the element identified by ref or selector: its trimmed textContent, or — when that is empty — the accessible label that electron_find matches on (aria-labelledby/aria-label, native labels, alt, title, placeholder), so a find-by-name then get_text chain works on labelled controls. Returns: { ok, session_id, text }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (no such element; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector or ref+selector both/neither).
Inputs: ref, selector, sessionId.
electron_get_valueGet a form control’s valueARead-only
Return the .value of the input/textarea/select identified by ref or selector (null if the element has no value). Returns: { ok, session_id, value }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: ref, selector, sessionId.
electron_hoverHover an elementA
Hover the element identified by ref or selector (e.g. to reveal a tooltip or menu). Options: force, timeoutMs. Returns: { ok, session_id, target }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), POINTER_NOT_DELIVERED (retryable), NOT_RUNNING, BAD_ARGUMENT.
Inputs: ref, force, selector, sessionId, +1 more.
electron_infoElectron app infoARead-only
Report the running Electron app environment: runtime versions (electron/node/chrome/v8), app name/version/paths, packaged flag, code-signature status (verified for packaged macOS apps; "unknown" for unpackaged/dev apps, "unsupported" off macOS), the active transport, and its capability matrix. Pass sessionId to target a specific session when several are running. Versions and app fields are null when the transport cannot evaluate in the main process (CDP sessions). Returns: { ok, session_id, transport, versions, app, signature, capabilities }. Errors: NOT_RUNNING (no session — call electron_launch first; not retryable), BAD_ARGUMENT (multiple sessions live — pass sessionId; not retryable).
Inputs: sessionId.
electron_injectInject into running Electron appA
Attach to a running Electron process that was NOT started with a debug flag, by injecting the Node inspector. Provide pid. Returns: { ok, session_id, transport, windows, capabilities }. Errors: INJECT_FAILED (handshake failed or inspector belongs to another process; retryable — try electron_attach when the app already exposes a debug endpoint), TRANSPORT_UNSUPPORTED, BAD_ARGUMENT.
Inputs: pid (required), timeoutMs.
electron_keyPress a key or chordA
Press a key or chord (e.g. 'Enter', 'Control+A', 'ArrowDown'). Focuses ref/selector first when given; otherwise presses against the active element. For editors, click the visible content area first; reserve force:true for offscreen inputs that truly accept focus. Options: force, timeoutMs, waitForFocusMs, requireEditable. Returns: { ok, session_id, key, focused }. Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), NO_FOCUSED_EDITABLE, NOT_RUNNING, BAD_ARGUMENT (ref+selector both).
Inputs: key (required), ref, force, selector, +4 more.
electron_keyboard_typeType text as real keystrokesA
Type text as real per-character keystrokes (fires keydown/keypress/input/keyup per char), unlike electron_type which sets the value directly. Focuses ref/selector first when given; otherwise types into the active element. For a code editor (Monaco / EditContext), the reliable path is electron_type_into_editor (it clicks the editor content area, e.g. '.monaco-editor .view-lines', then types into the focused editor) — do NOT target the hidden textarea, which modern editors ignore. force:true focuses an offscreen/aria-hidden input but a swallowed keystroke returns TYPE_NO_EFFECT. Options: force, timeoutMs, waitForFocusMs, requireEditable. Returns: { ok, session_id, typed, focused: { role, name, editable } | null } (where the keys went). Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), TYPE_NO_EFFECT (typing changed nothing — use electron_type_into_editor), NO_FOCUSED_EDITABLE, NOT_RUNNING, BAD_ARGUMENT.
Inputs: text (required), ref, force, selector, +4 more.
electron_launchLaunch Electron appA
Launch an Electron app and start a driving session. Provide main (absolute path to the main-process entry) or executablePath. When the server has --app-root, a main launch uses the Electron installed in that project (runtime_source "project"); if the project has none it uses the server's Electron and says why in runtime_fallback. runtime:"server" always uses the server's, runtime:"project" requires the project's; an explicit executablePath takes precedence. Executable-only launches are treated as packaged apps and use a transport-owned, loopback CDP endpoint; main-based development launches use Playwright. A server started with --demo supplies its packaged demo entry when both are omitted. Returns: { ok, session_id, transport, windows, renderer_ready, runtime_source, runtime_fallback?, launch_mode, capabilities }. credentialStore defaults to "testing": macOS receives --use-mock-keychain and Linux receives --password-store=basic so OS credential prompts cannot wedge automation. Use credentialStore:"system" when assertions must verify genuine safeStorage sealing. Waits (up to readyTimeoutMs, default 5000) for the renderer DOM to finish its initial render, so a snapshot/find right after launch sees a populated app; renderer_ready:false means it was not confirmed in time (the session is still usable — retry the read, or wait_for_selector on an expected element). By default refuses a second launch while a session is live (pass allowMultiple: true to override). Errors: ALREADY_RUNNING (a session is live, or the concurrent-session cap is reached — stop one or pass allowMultiple; not retryable), ABSOLUTE_PATH_REQUIRED / FILE_NOT_FOUND (preflight; not retryable), BAD_ARGUMENT (neither main nor executablePath given; runtime:"project" without main when no executablePath is given, or without --app-root when resolving that runtime; a runtime-altering env var like NODE_OPTIONS; instrumentNative without main; or, when the server set --app-root, a main/executablePath/cwd outside that root), FUSES_BLOCK_LAUNCH (a main-based development launch selected a binary that disables the Node CLI inspect channel Playwright requires; not retryable — use executablePath without main for packaged CDP launch, attach over CDP, or use a compatible development build), ELECTRON_RUNTIME_MISSING (a main-based launch without executablePath found no downloaded Electron binary or no electron package for the server; not retryable — run install-electron with the server's npx --package list, pass executablePath, or use runtime:"project"), SINGLE_INSTANCE_LOCK (another app instance holds the lock; not retryable), LAUNCH_FAILED (the packaged app could not start or exited before a driveable renderer; not retryable), LAUNCH_TIMEOUT (first window did not appear, often a main process blocked on an OS prompt or dialog; retryable), TRANSPORT_UNSUPPORTED (no launch-capable transport).
Inputs: cwd, env, args, main, +7 more.
electron_press_sequencePress a sequence of keysA
Press each key in keys, in order (e.g. ['Control+A', 'Delete', 'Enter']). Focuses ref/selector first when given. For editors, click the visible content area first; reserve force:true for offscreen inputs that truly accept focus. Options: force, timeoutMs, waitForFocusMs, requireEditable (checked before the first key). Returns: { ok, session_id, keys, focused }. Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), NO_FOCUSED_EDITABLE, NOT_RUNNING, BAD_ARGUMENT (empty keys or ref+selector both).
Inputs: keys (required), ref, force, selector, +4 more.
electron_reloadReload a windowA
Reload the active window (or windowId, which also selects it) and wait, within readyTimeoutMs (default 5000), for the new page to render, like electron_launch; then optionally for waitForSelector to be visible. Use it instead of location.reload() in eval. ignoreCache does a hard reload. Refs from before the reload are gone. Returns: { ok, session_id, renderer_ready, url }. Errors: WAIT_TIMEOUT (waitForSelector not visible in time; retryable), REF_NOT_FOUND (no such window), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector).
Inputs: windowId, sessionId, ignoreCache, readyTimeoutMs, +1 more.
electron_screenshotCapture a screenshotARead-only
Capture a screenshot to an image file and return its path (the image is written on the server host; the bytes are NOT returned inline). With ref/selector, captures just that element; otherwise the targeted window (windowId > windowTitle > windowIndex, default the active window) with optional fullPage or clip. Options: format (png|jpeg), quality (jpeg), path (absolute file) or dir (absolute directory, generated filename). With neither, writes to the server --screenshot-dir if configured, else the OS temp dir — pass dir or set --screenshot-dir for a stable, retrievable artifact location. Before capturing it waits settleMs (optional), then for the active window to paint a new frame (waitForFrame, default true). Returns: { ok, session_id, path, bytes, format, width?, height?, content_sha256, same_as_previous (same bytes as the last capture of this target), overwrote (path existed; a viewer may show a cached copy), frame_waited }. When portable delivery is available, artifact metadata and an MCP resource_link let the client read the generated bytes before expires_at; otherwise artifact_unavailable explains the limit. Errors: ABSOLUTE_PATH_REQUIRED (relative path), REF_NOT_FOUND (no such window), SELECTOR_NO_MATCH (element not found), SURFACE_UNSUPPORTED (iframe element crops are not window-relative), NOT_RUNNING, BAD_ARGUMENT (invalid selector/options), RENDERER_NAVIGATED (the page was navigating).
Inputs: format (required), waitForFrame (required), dir, ref, +10 more. Returns: object
electron_scrollScroll the page or an element into viewA
Scroll: with ref/selector, centre that element into view; otherwise dispatch a wheel delta (dx/dy). Options: timeoutMs. Returns: { ok, session_id, target } (into-view) or { ok, session_id, dx, dy } (wheel). Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (no element matched the selector; carries similar_refs), NOT_RUNNING, BAD_ARGUMENT (ref+selector both).
Inputs: dx, dy, ref, selector, +2 more.
electron_scroll_into_viewScroll an element into viewA
Centre the element identified by ref or selector into the viewport. Options: timeoutMs. Returns: { ok, session_id, target }. Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), NOT_RUNNING, BAD_ARGUMENT (ref+selector both/neither).
Inputs: ref, selector, sessionId, timeoutMs.
electron_select_optionSelect option(s) in a dropdownA
Select option(s) by value in the identified by ref or selector. Options: force, timeoutMs. Returns: { ok, session_id, target, selected } (selected = the values actually chosen). Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: values (required), ref, force, selector, +2 more.
electron_set_filesSet files on a file inputA
Set the files of the identified by ref or selector. Paths must be ABSOLUTE and exist on the host running the server (max 20 files, 52428800 bytes each). Options: timeoutMs. Returns: { ok, session_id, target, files }. Errors: ABSOLUTE_PATH_REQUIRED (relative path; not retryable), FILE_NOT_FOUND (missing path), BAD_ARGUMENT (too many/large files, or ref+selector both), SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), NOT_RUNNING.
Inputs: paths (required), ref, selector, sessionId, +1 more.
electron_set_window_sizeSet a window’s sizeA
Resize the active window (or windowId) to width x height, of the whole window or, with area "content", of its web content, without eval. Waits for the size to settle and reports what the window really got: an app minimum/maximum size or the screen can clamp it. A maximized or fullscreen window is restored first. Returns: { ok, session_id, window_id, requested, actual, clamped, clamped_by?, window, content, min_size, max_size, restored_from?, method }; clamped_by is minimum_size, maximum_size or window_system; min_size/max_size are null when unset or unknown. CDP attach resizes from the page: it cannot read the limits, and content is the page viewport in CSS pixels (scaled by page zoom). Errors: REF_NOT_FOUND (no such window), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: width (required), height (required), area, windowId, +1 more.
electron_snapshotSnapshot renderer accessibility treeARead-only
Capture the selected renderer surface accessibility tree: interactive elements (and landmarks) with role, name, state, bbox, and a stable ref. Pass since:"last" for only what changed since the previous snapshot (added/removed/changed + ref_map), interactiveOnly to drop landmarks, maxEntries to cap, root to return one subtree. format:"text" returns a compact one-line-per-entry rendering instead of JSON (5-10x fewer tokens): [ref] role "name" value=… flags, ~ marks recently-changed, [-] marks landmarks. Diffs default to a compact encoding (changed fields only; diffFormat:"full" restores complete prev/curr entries) and accept budgetTokens for server-side truncation that keeps interactive entries first. Each response carries renderer_reloaded so stale refs are detectable (P10). Refs are tagged on the DOM (data-sw-ref) so later interaction tools can act by ref. Closed shadow roots are opaque unless the app opts in: push each root onto window.__stagewright_closedShadowRoots at attachShadow time (or implement window.__stagewright_inspectShadow); their entries carry state.shadow_closed: true. Returns: { ok, surface_id, kind: "full" | "diff", snapshot?, diff?, snapshot_text?, diff_text?, diff_format?, renderer_reloaded, truncated }. Errors: NOT_RUNNING (no session — call electron_launch first; not retryable), BAD_ARGUMENT (multiple sessions live — pass sessionId; bad root), REF_NOT_FOUND / SELECTOR_NO_MATCH (root missing).
Inputs: root, since, format, sessionId, +4 more.
electron_statusElectron Stagewright statusARead-only
Return compact orientation for this server: version, start time, uptime, the last stable failure not tied to a live session, active-session count, and each live session's transport, renderer readiness, selected surface, last stable error code, and non-default dialog policy. It never returns arguments, paths, window arrays, logs, stack traces, dialog entries, prompt text, or plugin payloads. Use electron_windows_list, electron_surfaces_list, or the relevant plugin tool for detailed state. Returns: { ok, server: { version, started_at, uptime_ms, last_error? }, active_sessions, sessions }. Errors: none.
Inputs: no named parameters.
electron_stopStop Electron appADestructive
Gracefully stop a session and release it. If the app ignores the close within timeoutMs (default 10s) the stop auto-escalates to SIGKILL, so the process is always reaped and never left orphaned; the response reports escalated: true when that happened. Pass sessionId to target a specific session. Returns: { ok, session_id, stopped: true, escalated }. Errors: NOT_RUNNING (no such session; not retryable), BAD_ARGUMENT (multiple sessions live — pass sessionId).
Inputs: sessionId, timeoutMs.
electron_surfaces_listList Electron renderer surfacesARead-only
List the session renderer surfaces in parent-first order: BrowserWindow roots, WebContentsViews, webview guests, and iframe children. Each opaque id is stable only while its surface stays live; select it with electron_switch_surface before snapshot/find/renderer interactions. Returns: { ok, session_id, surfaces, active_surface_id, count }. Existing window tools remain compatible for window-only flows. Errors: TRANSPORT_UNSUPPORTED (surface targeting is unavailable on this transport; not retryable), NOT_RUNNING, BAD_ARGUMENT (multiple sessions).
Inputs: sessionId.
electron_switch_surfaceSwitch active renderer surfaceA
Select a live renderer surface by the opaque id returned by electron_surfaces_list. Following snapshot, find, renderer reads/eval, waits, expectations, and interactions target that surface; a ref from a different surface is rejected rather than reused. Returns: { ok, session_id, active, active_surface_id }. Errors: SURFACE_NOT_FOUND (the id was never observed in this session), SURFACE_CLOSED (it detached or closed), SURFACE_UNSUPPORTED (the live surface cannot be driven), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: surfaceId (required), sessionId.
electron_switch_windowSwitch active Electron windowA
Select the active window by precedence targetId > windowTitle > index > default. The selection changes Stagewright's renderer target; it does not promise native OS foreground focus. Returns: { ok, session_id, active, active_window_id } on success. Errors: REF_NOT_FOUND (no window matched; not retryable), TRANSPORT_UNSUPPORTED (transport has no renderer window target; not retryable), NOT_RUNNING, BAD_ARGUMENT (multiple sessions).
Inputs: index, targetId, sessionId, windowTitle.
electron_typeType text into an inputA
Set the value of the input/textarea identified by ref or selector (fires an input event). For a code editor (Monaco / EditContext, CodeMirror) use electron_type_into_editor — setting .value on an editor host does not update its model. Options: force, timeoutMs. Returns: { ok, session_id, target }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, TYPE_NO_EFFECT (value did not change — wrong target), NOT_RUNNING, BAD_ARGUMENT.
Inputs: text (required), ref, force, selector, +2 more.
electron_type_into_editorType into a code editorA
Type into a code editor (Monaco / EditContext, CodeMirror, contenteditable) the reliable way: click the editor's content area identified by ref or selector (e.g. '.monaco-editor .view-lines'), then type the text into the now-focused editor as real keystrokes. Use this instead of typing into an editor's hidden textarea, which modern EditContext editors ignore (returns TYPE_NO_EFFECT). Pass replace:true to REPLACE the editor contents: after the focusing click it selects all (Meta/Control+A, platform-aware) and types over the selection — no second click that would collapse the selection; with empty text it clears the editor (select-all + Delete). Editor auto-pairing caveat: real keystrokes trigger auto-closing of quotes/brackets, so typed source can gain debris like a trailing }') — type pairing-safe fragments, or use replace:true and include the full intended contents. Returns: { ok, session_id, target, typed, replaced }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), TYPE_NO_EFFECT, NOT_RUNNING, BAD_ARGUMENT.
Inputs: text (required), ref, replace, selector, +2 more.
electron_uncheckUncheck a checkboxA
Uncheck the checkbox identified by ref or selector (no-op if already unchecked). Options: force, timeoutMs. Returns: { ok, session_id, target, checked: false }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, NOT_RUNNING, BAD_ARGUMENT.
Inputs: ref, force, selector, sessionId, +1 more.
electron_waitWait a fixed durationARead-only
Pause for ms milliseconds (clamped to 60000). Prefer electron_wait_for_state or electron_wait_for_selector — a fixed wait is slower and more brittle than waiting on a condition. Returns: { ok, session_id, waited_ms }. Errors: NOT_RUNNING (no session), BAD_ARGUMENT (multiple sessions).
Inputs: ms (required), sessionId.
electron_wait_for_eventWait for a DOM eventARead-only
Wait until a named DOM event (e.g. "transitionend", "load", a custom event) fires on the element identified by ref or selector — or on document when neither is given. Returns: { ok, session_id, fired, event }. Errors: WAIT_TIMEOUT (event did not fire within timeoutMs; retryable), SELECTOR_NO_MATCH (target element not present), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, or ref+selector both).
Inputs: eventName (required), ref, selector, sessionId, +1 more.
electron_wait_for_selectorWait for a selector stateARead-only
Wait until the element identified by ref or selector reaches state: attached (in the DOM), visible (laid out + not visibility:hidden), hidden (absent or not visible), or detached (removed). Default state: visible. For an intentionally offscreen / aria-hidden element (e.g. a code editor's hidden textarea like Monaco), wait for state:'attached' — state:'visible' will time out because the element is never laid out. Returns: { ok, session_id, matched, state }. Errors: WAIT_TIMEOUT (condition not met within timeoutMs; retryable — for offscreen editor inputs use state:'attached'), REF_NOT_FOUND (stale ref; carries similar_refs), RENDERER_NAVIGATED, TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, or ref+selector both/neither).
Inputs: state (required), ref, selector, sessionId, +1 more.
electron_wait_for_stateWait for an element stateARead-only
Wait until the element identified by ref or selector matches the given state flags (any of visible, enabled, disabled, checked, selected, expanded, pressed, focused, readonly, required, invalid, busy), evaluated atomically. Returns: { ok, session_id, matched, state }. Errors: WAIT_TIMEOUT (state not reached within timeoutMs — details.last_state shows the last observed state; retryable), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, no state flags, or ref+selector both/neither).
Inputs: state (required), ref, selector, sessionId, +1 more.
electron_windows_listList Electron windowsARead-only
List the app windows with their id, index, title, url, and visibility. Pass sessionId to target a specific session. Returns: { ok, session_id, windows, active_window_id, count }. Errors: NOT_RUNNING (no such session; not retryable), BAD_ARGUMENT (multiple sessions — pass sessionId).
Inputs: sessionId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 57 tools
Most tools target a distinct action, but several pairs are near-duplicates: electron_expect_state vs electron_wait_for_state, electron_expect_visible vs electron_wait_for_selector(state:visible), and electron_scroll (with a ref, it centres the element) vs electron_scroll_into_view. Typing tools (electron_type, electron_keyboard_type, electron_type_into_editor, electron_key, electron_press_sequence) and the launch/stop/force_kill/detach lifecycle cluster also require careful reading of long descriptions to pick correctly. The documentation is thorough enough to resolve most of this, but selection errors remain plausible.
All tools use snake_case under a uniform electron_ prefix, with clear verb-based names (electron_click, electron_get_text, electron_expect_url). The only deviation is a handful of noun-first names (electron_surfaces_list, electron_elements_list, electron_windows_list) that invert the verb_noun order used elsewhere. Readable and predictable overall.
At 57 tools this is far past a comfortable surface for one server, and the count is inflated by parallel families (six electron_expect_* tools, three electron_wait_for_* plus electron_wait, two scroll tools) that could be consolidated. The domain is genuinely large (launch, inspect, interact, assert, artifacts), so not every tool is gratuitous, but the surface is heavy enough that an agent must triage before acting.
Coverage of driving an Electron app is broad: launch/attach/inject, session lifecycle, surfaces and windows, snapshot/find/read, full interaction set, waits/asserts, console logs, dialogs, and screenshots. However, several descriptions repeatedly reference an 'eval' capability (doctor's eval policy, switch_surface's 'renderer reads/eval', reload's 'instead of location.reload() in eval') yet no eval tool exists in the set, and there is no network/interception or clipboard tool. Those gaps will block some otherwise natural workflows.
Maintenance
Related MCP Connectors
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Autonomous cloud agent tasks: real browser + your tools, structured evidence-backed results.
Write, run and check natural-language browser tests of your web app from your AI assistant.
Related MCP Servers
- AlicenseAqualityCmaintenancePlaywright for the entire OS. Give AI agents eyes and hands on any desktop app — find, click, type, and read UI elements across Linux, macOS, and Windows.2748MIT
- AlicenseAqualityDmaintenanceDrive Electron apps from AI agents via MCP - click, type, drag, screenshot, eval JS, and more.3994 npm3MIT
- AlicenseCqualityDmaintenanceEnables AI coding tools to interact with Electron applications for automated testing, including app lifecycle, element interaction, and visual testing.489 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to safely and truthfully control local desktop applications via native accessibility trees, supporting element inspection and automation without proprietary binaries or fake success responses.Apache 2.0