# @yawlabs/electron-mcp

[![npm version](https://img.shields.io/npm/v/@yawlabs/electron-mcp)](https://www.npmjs.com/package/@yawlabs/electron-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/YawLabs/electron-mcp)](https://github.com/YawLabs/electron-mcp/stargazers)

**Make your AI assistant actually good at Electron.** 18 tools for the stuff AI models hallucinate about: context isolation, preload bridges, fuses, CSP, signing, auto-updates, breaking changes between majors, and the 20 official security recommendations.

This is not a runtime debugger. It is a development-intelligence layer that turns "write me some Electron code" from hit-or-miss into correct-on-the-first-try.

Built and maintained by [Yaw Labs](https://yaw.sh).

[![Add to Yaw MCP](https://yaw.sh/yaw-mcp-button.svg)](https://yaw.sh/mcp/install?name=Electron&command=npx&args=-y%2C%40yawlabs%2Felectron-mcp&description=Electron.js%20development%20intelligence%20-%20IPC%2C%20security%2C%20builds%2C%20migration&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Felectron-mcp)

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

## Why this one?

Other Electron MCP servers give your model a shell and hope. This one doesn't.

- **IPC that isn't a security hole** — `electron_scaffold_ipc_channel` generates main handler + typed preload bridge + contextBridge exposure + renderer usage in one call. No `nodeIntegration: true`, no direct `ipcRenderer` on `window`.
- **The official security recommendations, enforced** — `electron_audit_security` checks your `BrowserWindow` config, preload scripts, and CSP against 19 of the 20 items from [electronjs.org/docs/latest/tutorial/security](https://www.electronjs.org/docs/latest/tutorial/security) that can be verified from static inputs. (The 20th, session permission handling, needs runtime context and is flagged in the report footer.) Not a vibe check.
- **Version-aware migration** — `electron_migrate_version` knows the breaking changes from v28 through v41 and tells you exactly what will break when you bump. `electron_check_deprecated_apis` scans your code for APIs that were removed.
- **Build errors, explained** — `electron_diagnose_build_error` parses electron-builder/forge output and identifies root causes: Apple signing, Windows code signing, native module rebuilds, ASAR packaging, entitlements, path quoting.
- **Modern production hardening** — `electron_configure_fuses` generates the `@electron/fuses` block for disabling unused runtime features (cookie encryption, Node CLI flags, legacy load behaviour). `electron_configure_csp` generates a CSP that actually works with your bundler and framework instead of blocking your own assets.
- **Knowledge freshness is declared, not assumed** — every response includes a `_Knowledge last verified YYYY-MM-DD (Electron vN stable)_` footer. Call `electron_knowledge_version` to get the metadata directly. If your Electron is newer than the footer, the tool tells you.
- **Read-only, no side effects** — every tool declares `readOnlyHint`, `destructiveHint: false`, `idempotentHint: true`, so MCP clients can skip confirmation. The tools never touch your filesystem, never run code, never call `exec`.
- **Zero runtime dependencies** — ships as a single bundled file. No 5-minute `node_modules` install, no `electron` or `electron-builder` installed as dependencies to inflate your project. The published package's `dependencies` is `{}`; Dependabot alerts on this repo are against devDependencies (the MCP SDK's optional HTTP transport surface) which the bundle doesn't include — this server uses stdio only.

## Quick start

No API keys. No environment variables required. Just install it.

**1. Create `.mcp.json` in your project root**

macOS / Linux / WSL:

```json
{
  "mcpServers": {
    "electron": {
      "command": "npx",
      "args": ["-y", "@yawlabs/electron-mcp@latest"]
    }
  }
}
```

Windows:

```json
{
  "mcpServers": {
    "electron": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/electron-mcp@latest"]
    }
  }
}
```

> **Why the extra step on Windows?** Since Node 20, `child_process.spawn` cannot directly execute `.cmd` files (that's what `npx` is on Windows). Wrapping with `cmd /c` is the standard workaround.

**2. Restart and approve**

Restart Claude Code (or your MCP client) and approve the Electron MCP server when prompted.

That's it. Now ask your AI assistant:

> "Add a file picker to my Electron app"
>
> "Audit my BrowserWindow config for security issues"
>
> "My electron-builder is failing with a signing error — here's the output"
>
> "Generate a CSP for my Vite + React renderer"
>
> "What breaks if I upgrade from Electron 32 to 41?"

## Alternate MCP clients

| Client | Config file |
|---|---|
| Claude Code | `.mcp.json` (project root) or `~/.claude.json` (global) |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
| Cursor | `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| VS Code | `.vscode/mcp.json` |

Use the same JSON block shown above in any of these.

## Runtime and sandbox

The launcher prefers the [oam](https://oamjs.org) runtime when a current one (0.15.2 or newer) is installed, and falls back to the Node that is already running it. Nothing to configure; both serve the same server.

**Opt-in sandbox.** With oam, the server can run under `--permission` with no grants at all: no filesystem, no child processes, no network, no environment. This server needs none of them (every tool computes over its arguments and returns markdown), so the sandbox costs no capability and turns anything the server merely happens not to use into a runtime refusal. Add an `env` block to whichever config block you used above (`npx` on macOS / Linux / WSL, `cmd /c npx` on Windows):

```json
"env": { "ELECTRON_MCP_SANDBOX": "1", "ELECTRON_MCP_RUNTIME": "oam" }
```

The second variable is what makes the sandbox **required**: it needs a freshly spawned oam (0.15.2 or newer) to apply it, and with `ELECTRON_MCP_RUNTIME=oam` a missing or unusable oam is a startup error instead of an unsandboxed server. Under the default `ELECTRON_MCP_RUNTIME=auto` the launcher still serves in that case, **without** `--permission`, and prints a line on stderr saying so and how to fix it. Use `auto` when you want the sandbox where available; use `oam` when you want to be sure.

How to tell it took: every path that serves without the sandbox after it was asked for prints an `electron-mcp:` line on stderr containing `runs WITHOUT --permission`, plus how to fix it (most MCP clients show server stderr in their logs). When the sandbox is applied there is no such line. To confirm from a shell:

```sh
ELECTRON_MCP_SANDBOX=1 ELECTRON_MCP_RUNTIME=oam npx -y @yawlabs/electron-mcp@latest --version
```

The version on stdout, exit 0, and no `WITHOUT --permission` line means a sandboxed oam served it; with `ELECTRON_MCP_RUNTIME=oam` set, a missing oam is an error instead.

It is off by default because it is a behaviour change: a future version that legitimately needs a capability should fail in review, not in your session. Two more things to know:

- If the launcher itself is already running under oam (Yaw MCP does this), the sandbox spawns a second oam (the host's own binary, if nothing newer is installed), because only a fresh one can apply a process-level flag. That adds one runtime boot to startup, plus a `--version` probe per oam binary the launcher finds.
- Request the sandbox through the variable, not by putting `--permission` on the host command: a launcher running under `--permission` cannot read its environment, so every `ELECTRON_MCP_*` setting would be ignored. (The direct, no-launcher form is `oam --permission run <path>/dist/index.js`.)

| Variable | Effect |
|---|---|
| `ELECTRON_MCP_RUNTIME=auto` | newest usable oam, else Node (default) |
| `ELECTRON_MCP_RUNTIME=oam` | newest usable oam, else exit with an error |
| `ELECTRON_MCP_RUNTIME=node` | always Node (the sandbox is not applied, and the launcher says so) |
| `ELECTRON_MCP_SANDBOX=1` | run oam under `--permission` with no grants; `true` / `yes` / `on` also enable it, `0` / `false` / `no` / `off` disable it |
| `OAM_BIN=/path/to/oam` | use this oam when it is usable, before discovery |

Both values are case-insensitive and trimmed. A value the launcher does not recognise is never a silent no-op: it is treated as the default (`auto`; sandbox off) and named on stderr, so a typo cannot quietly turn "sandbox required" into "sandbox if convenient".

## Tools (18)

### IPC & process architecture (5)
- **electron_scaffold_ipc_channel** — Generate a complete IPC round-trip: main handler, preload bridge, `contextBridge` exposure, TypeScript types, renderer usage.
- **electron_generate_preload_bridge** — Generate a secure `preload.ts` with `contextBridge` for multiple API methods.
- **electron_audit_ipc_security** — Analyze preload/main/renderer code for IPC security issues (direct `ipcRenderer`, missing sender validation, channel injection).
- **electron_generate_window_manager** — Multi-window management with lifecycle tracking and inter-window communication.
- **electron_explain_process_model** — Version-aware explanation of Electron's multi-process architecture (main vs renderer vs utility, what lives where).

### Security (4)
- **electron_audit_security** — Audit against 19 of the 20 official security recommendations that can be detected from static inputs: BrowserWindow, preload, CSP, remote content, sandbox. (Session permission handling is the 20th; it needs runtime context and is flagged in the report footer.)
- **electron_configure_fuses** — Generate `@electron/fuses` config for production hardening (disable cookie encryption fallback, Node CLI flags, legacy load behaviour).
- **electron_configure_csp** — Generate a Content Security Policy aware of your bundler (Vite/webpack/Parcel) and framework (React/Vue/Svelte).
- **electron_lint_security** — Static analysis for dangerous patterns: `shell.openExternal` with untrusted input, `@electron/remote`, `enableBlinkFeatures`, etc.

### Build & distribution (4)
- **electron_diagnose_build_error** — Parse electron-builder/forge errors and identify root causes: code signing, native modules, ASAR, entitlements, path quoting.
- **electron_configure_auto_update** — Generate complete `electron-updater` setup with events and platform-specific signing concerns.
- **electron_configure_deep_linking** — Custom protocol registration across Windows/macOS/Linux.
- **electron_scaffold_project** — Generate a secure, modern Electron project scaffold (contextIsolation: true, sandbox: true, preload, TypeScript, chosen framework).

### Migration & compatibility (2)
- **electron_migrate_version** — Migration checklist between Electron versions with breaking changes, deprecated APIs, platform support changes.
- **electron_check_deprecated_apis** — Scan source for APIs deprecated or removed in the target Electron version.

### Performance (1)
- **electron_audit_performance** — Detect the 7 official Electron performance anti-patterns (sync I/O on main, eager loading of heavy modules, etc).

### Reference (2)
- **electron_explain_concept** — Authoritative explainer for 8 topics: process model, context isolation, sandbox, IPC, ASAR, fuses, code signing, build tools.
- **electron_knowledge_version** — Metadata about the embedded knowledge: last-verified date, Electron stable at verification, supported version range. Call this if an agent is unsure whether advice is current.

## Knowledge freshness

Tools that depend on embedded Electron knowledge (breaking changes, deprecated APIs, security recommendations, anti-patterns, concept explanations) append a footer like:

```
_Knowledge last verified 2026-04-13 (Electron v41 stable). For anything newer, check https://releases.electronjs.org._
```

Call `electron_knowledge_version` to get the metadata directly. When a new Electron major releases, [KNOWLEDGE.md](./KNOWLEDGE.md) documents the update process.

## Examples

### Add a file picker the safe way

```
> "Add a file picker that lets the renderer read the selected file's contents"
→ electron_scaffold_ipc_channel({
    direction: "renderer-to-main",
    channel: "open-file",
    returns: "string"
  })
  # Generates: main handler (dialog.showOpenDialog + fs.readFile),
  # preload bridge (contextBridge.exposeInMainWorld),
  # TypeScript types for window.api.openFile,
  # renderer usage example
```

### Audit an existing app's security

```
> "Check my Electron app for security issues — here's my main.ts and preload.ts"
→ electron_audit_security({ mainCode: "...", preloadCode: "..." })
  # Returns a graded report against 19 of 20 recommendations
  # (session permissions needs runtime context),
  # flagging nodeIntegration, missing contextIsolation,
  # unsandboxed renderers, loose CSP, and more.
```

### Diagnose a failing signing step

```
> "electron-builder is exiting with: errSecInternalComponent — help"
→ electron_diagnose_build_error({ output: "..." })
  # Identifies macOS Keychain Access issue with code signing,
  # returns specific `security` CLI fix and CI reconfiguration.
```

### Plan an Electron major bump

```
> "We're on Electron 32. What breaks if we jump to 41?"
→ electron_migrate_version({ from: 32, to: 41, sourceCode: "..." })
  # Returns breaking changes across each major (33, 34, 35, ...),
  # deprecated APIs found in your code,
  # platform support changes,
  # recommended test plan.
```

### Generate a real CSP

```
> "Generate a CSP for my Vite + React renderer that actually works"
→ electron_configure_csp({
    bundler: "vite",
    framework: "react",
    allowedOrigins: ["https://api.mycompany.com"]
  })
  # Returns a CSP that accounts for Vite's dev-mode WebSocket,
  # React's inline runtime, and blocks everything else.
```

## Troubleshooting

**"Tool output is cut off / too long"**

- A few scaffolders produce >10KB of generated code. Ask the assistant to regenerate with a narrower scope (single channel vs multi-channel bridge; one framework scaffold vs comparison).

**"The advice is wrong for my Electron version"**

- Check `electron_knowledge_version`. If Electron has shipped a new major since the verified date, cross-check with the official breaking-changes page linked there.
- File an issue on the repo with the specific tool + version + expected vs actual. Knowledge updates ship in minor versions.

**"Windows: MCP server doesn't start"**

- Use the `cmd /c npx ...` pattern from the Quick start section. Node 20+ can't spawn `.cmd` files directly.

## Requirements

- Node.js 20.11+
- No runtime dependencies

## Contributing

```bash
git clone https://github.com/YawLabs/electron-mcp.git
cd electron-mcp
npm install
npm run lint       # Biome check
npm run lint:fix   # Auto-fix
npm run build      # tsc + esbuild bundle
npm test           # node --test
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow, including release process.

## License

MIT

[![Follow @TokenLimitNews on X](https://img.shields.io/badge/follow-%40TokenLimitNews-000000?logo=x&logoColor=white)](https://x.com/TokenLimitNews)