# core

An MCP server that drives real Electron apps: it launches or attaches, reads the accessibility tree, clicks stable refs and asserts state with retries.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 12
- Author: electron-stagewright
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/electron-stagewright/electron-stagewright
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/electron-stagewright-core

## What it does

The server gives an agent a handle on a running Electron app. It can start one or join an existing process, inspect the accessibility tree, and interact through element references that survive a re-render. Assertions use `expect_*` primitives with a timeout, so the usual read-compare-retry loop collapses into a single call.

Tools include `electron_launch`, `electron_attach`, `electron_snapshot`, `electron_find`, `get_state` and `wait_for_state`. Errors arrive with hints and near-miss refs, each response reports its token cost, and `get_state` returns the whole state of an element at once: visible, enabled, checked, focused. A snapshot marks what changed since the previous one and can return just the delta. Session traces can be replayed against a fresh app instance, with token budgets to stop runaway loops. Packaged builds get their own coverage: signing, Gatekeeper assessment and the autoUpdater feed.

Node.js 24 or newer is required. On Linux the server also needs a display, either `DISPLAY`, `WAYLAND_DISPLAY` or `xvfb-run -a`. Electron fetches its binary on first use rather than at install time, and that download writes a progress line to stdout, which would land in the MCP protocol stream. Fetch it beforehand with `install-electron`, then run `doctor` and check for exit code 0. Keep the `--package` list identical across commands, since `npx` caches each list on its own.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add core -- npx -y @electron-stagewright/core
```

### Codex

**Platform CLI**
```bash
codex mcp add electron-stagewright-core -- npx -y @electron-stagewright/core
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "electron-stagewright-core": {
            "command": "npx",
            "args": [
                "-y",
                "@electron-stagewright/core"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "electron-stagewright-core": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@electron-stagewright/core"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add electron-stagewright-core npx -y @electron-stagewright/core
```

## When to use it
- launch an Electron app from an agent session and list its windows
- confirm a button became enabled without a chain of follow-up calls
- locate an element by role and partial name instead of a CSS selector
- attach to a dev server that is already running, without a restart
- check signing and packaging of a finished `.app` bundle

## Example prompts
- Launch the app and show me the accessibility tree of the main window.
- Find the button whose name contains "Submit" and verify it is enabled within 5000 ms.
- Attach to the running dev server and diff the snapshot against the last one.

## Similar
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74559
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [SeleniumBase MCP](https://affpapa.org/en/nevibecode/mcp/seleniumbase-mcp.md) — MCP server · ★ 13169
- [mobile-mcp](https://affpapa.org/en/nevibecode/mcp/mobile-mcp.md) — MCP server · ★ 9946
- [e2e](https://affpapa.org/en/nevibecode/mcp/e2e.md) — MCP server · ★ 11912
- [mockserver](https://affpapa.org/en/nevibecode/mcp/mockserver.md) — MCP server · ★ 4996

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md