에이전트 강화
게시자의 자체 명령입니다. PlugMCP 엔드포인트가 아닙니다.
Host a copy with our keys and logs.
npx -y @electron-stagewright/[email protected]Claude Code에는 로컬 명령용 설치 링크가 없습니다. 아래 명령을 복사해 터미널에서 실행합니다.
claude mcp add electron-stagewright-electron-stagewright -- npx -y @electron-stagewright/core@0.10.0터미널에서 실행합니다.
{ "mcpServers": { "electron-stagewright-electron-stagewright": { "command": "npx", "args": [ "-y", "@electron-stagewright/[email protected]" ] } }}claude_desktop_config.json
원격 URL인가요, 내 컴퓨터에서 실행하는 명령인가요? 두 설치 방식의 차이
PlugMCP에서 실행
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
실행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.
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:
get_state returns 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_state accepts composite predicates — { visible: true, enabled: true, focused: false } evaluated atomically by the server. One call replaces three.recently_changed elements — agents focus reasoning on what differs from the last view instead of reprocessing the whole tree.electron_snapshot({ since: 'last' }) returns only deltas. Fewer APIs to remember.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_find queries the accessibility tree semantically — { role: 'button', name_contains: 'Submit', visible: true } — no CSS selectors, no XPath, no guessing.The server treats three Electron-specific workflows as first-class:
electron_attach connects to apps exposing a loopback CDP endpoint, and electron_inject can attach to a running main process via the Node Inspector handshake when no debug flag was arranged up front.trace.zip but 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..app bundles — 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.
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/[email protected] \
--package [email protected] --package [email protected] install-electron
npx -y --prefix ~/ --package @electron-stagewright/[email protected] \
--package [email protected] --package [email protected] electron-stagewright doctor --json
claude mcp add electron-stagewright -- \
npx -y --prefix ~/ --package @electron-stagewright/[email protected] \
--package [email protected] --package [email protected] \
electron-stagewright --tool-profile essential
claude 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/[email protected] 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.js
Shared project .mcp.json shape:
{
"mcpServers": {
"electron-stagewright": {
"command": "npx",
"args": [
"-y",
"--prefix",
"~/",
"--package",
"@electron-stagewright/[email protected]",
"--package",
"[email protected]",
"--package",
"[email protected]",
"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).
expect_* family,
waits, and snapshot diffs.replace, the auto-pairing caveat, and how to verify the text landed.electron_plugins.--allow-eval, and a deployment checklist.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).
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.
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.
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 and WebContentsView surface 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).
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:
If your Electron app has a shape these don't cover, open an issue — we'd love to add it as an example fixture.
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.
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.
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.
MIT — see LICENSE.
Drive Electron apps the way Playwright drives browsers — MCP server for AI agents.
{ "mcpServers": { "electron-stagewright-electron-stagewright": { "command": "npx", "args": [ "-y", "@electron-stagewright/[email protected]" ] } }}도구
아직 도구 목록이 없습니다. 원격 서버는 첫 상태 확인 후에 도구 목록이 생깁니다.
FAQ
이 페이지에서 Cursor, Claude Desktop, Claude Code 또는 VS Code용 stdio 설정을 복사합니다. PlugMCP 프록시가 아니라 게시자의 설치 방식을 사용합니다.
이 레코드에는 필수 환경 변수가 등록되어 있지 않습니다.
Electron Stagewright은(는) stdio를 통해 로컬에서 실행됩니다.
마지막 확인: 2026-10-28. Drive Electron apps the way Playwright drives browsers — MCP server for AI agents.