Electron Stagewright docs

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. Three forms, fastest to set up first:

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": "npx",
      "args": [
        "-y",
        "--package",
        "@electron-stagewright/core",
        "--package",
        "playwright",
        "electron-stagewright"
      ]
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "electron-stagewright": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "@electron-stagewright/core",
        "--package",
        "playwright",
        "electron-stagewright"
      ]
    }
  }
}

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:

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

{
  "args": [
    "-y",
    "--package",
    "@electron-stagewright/core",
    "--package",
    "playwright",
    "electron-stagewright",
    "--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 is not installed The core package was started without its optional Playwright peer Use the npx --package @electron-stagewright/core --package playwright electron-stagewright form, or install both packages globally.
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.
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