Electron Stagewrightdocs

Connect your MCP client

Wire the published server into your MCP client — Claude Desktop, Cursor, or any MCP-capable host — and confirm it connected, so an agent can drive your own Electron app. This is the task-oriented counterpart to Getting started: that tutorial clones the repository to drive the bundled example; here you install the published package and point your client at it.

The server speaks the Model Context Protocol over stdio — your client spawns it as a child process and exchanges JSON-RPC frames over stdin/stdout. You give the client a command and args that launch the server; everything else is the client's standard MCP configuration.

Before you start

Pick how the client launches the server

The client needs a command and args that start the stdio server. Prefer a pinned, project-local install: it avoids registry work during normal client startup, travels with the project's lockfile, and gives --app-root a stable security boundary.

Configure your client

Each client stores MCP servers in its own config file. Claude Desktop and Cursor use the common mcpServers JSON shape shown below — a named entry with the command/args you picked above. Other hosts may wrap the same command and arguments in a different schema, so confirm yours against the client's own MCP docs.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\), then fully restart the app:

{
  "mcpServers": {
    "electron-stagewright": {
      "command": "node",
      "args": [
        "/absolute/path/to/your-electron-app/node_modules/@electron-stagewright/core/dist/cli.js",
        "--tool-profile",
        "essential",
        "--app-root",
        "/absolute/path/to/your-electron-app"
      ]
    }
  }
}

Cursor

Add an MCP server in .cursor/mcp.json (project-scoped) or the global ~/.cursor/mcp.json, then reload:

{
  "mcpServers": {
    "electron-stagewright": {
      "command": "node",
      "args": [
        "/absolute/path/to/your-electron-app/node_modules/@electron-stagewright/core/dist/cli.js",
        "--tool-profile",
        "essential",
        "--app-root",
        "/absolute/path/to/your-electron-app"
      ]
    }
  }
}

Any other MCP host

Use the same command and args in whatever stdio-server schema your host expects. Any host that spawns a stdio MCP server can run this one; the transport contract is the child process's stdin and stdout.

Server flags

Append flags to args (after the package/CLI). The common ones:

Profile Intended surface electron_screenshot
essential Focused launch, inspect, interact, and assert No
testing Broader test driving with screenshot evidence Yes
debug Attach, inspect, and diagnostics Yes
full Complete compatibility surface Yes

--screenshot-dir supplies the default output directory when the selected profile exposes electron_screenshot; use testing, debug, or full when stable screenshot artifacts are part of the workflow.

With npx, server flags follow the electron-stagewright bin name:

{
  "args": [
    "-y",
    "--package",
    "@electron-stagewright/core@0.5.0",
    "--package",
    "playwright@1.61.1",
    "--package",
    "electron@42.3.0",
    "electron-stagewright",
    "--tool-profile",
    "essential",
    "--app-root",
    "/absolute/path/to/your-electron-app",
    "--allow-eval=renderer"
  ]
}

Verify it connected

After saving the config and restarting the client:

  1. The client lists the server's tools. You should see the electron_* catalog — electron_launch, electron_snapshot, electron_find, and the rest. If electron_eval_main and electron_eval_renderer are absent, that is expected: they only appear when you pass --allow-eval.
  2. Drive one round-trip. Ask the agent to electron_launch your app, then electron_snapshot. A populated snapshot — the accessibility tree with numbered refs — means the wiring works. End with electron_stop so no app process outlives the session.

No host handy? The Getting started scripted scenario connects a real MCP client over stdio without any host, which is a quick way to confirm the server itself runs.

Troubleshooting

The failure modes are almost all about the stdio channel or the spawn command.

Symptom Likely cause Fix
Server shows "failed" / disconnects immediately Something wrote to stdout — for a stdio server, stdout is the protocol channel, so any stray print corrupts the stream The server sends all diagnostics to stderr by design. If you wrapped it in a shell script, make sure the wrapper prints nothing to stdout.
Client reports "server not found" / no tools Wrong command/args With npx, confirm the exact package name. With the local-checkout form, the path must be absolute and you must have run pnpm build.
Server won't start; a version/engine error Node below the version floor The server requires Node 24+. Check node -v; with npx, the client must resolve a new-enough Node.
electron_launch reports that Playwright or Electron is not installed The core package was started without an optional launch peer Use the pinned npx form shown above, install all three packages globally, or pass executablePath to electron_launch.
project_runtime warns about ABI or a native addon The server's default Electron differs from the app's runtime, or inventory is incomplete Start the server with --app-root <project>, run electron-stagewright doctor --json, then launch with runtime: "project" when appropriate.
electron_eval_main / electron_eval_renderer missing Eval tools are gated off by default Add --allow-eval (or --allow-eval=renderer / =main) to args. Read the security model first.
A known core tool is missing The selected core profile does not include it Restart with the profile named in the tool's recovery hint, or use --tool-profile full.
electron_launch returns FUSES_BLOCK_LAUNCH A main-based Playwright launch selected a runtime that disables the Node CLI inspect fuse For a packaged app, launch with executablePath and no main; otherwise use a compatible development runtime.
The app won't launch from electron_launch main is not an absolute path, or the app needs attach/inject Pass an absolute main; see Launch, attach, or inject for apps that are already running.

Where next