Electron MCP Server

An agent that can only read your repo cannot see an Electron window. This server is that debugger. It runs locally, speaks MCP over stdio, and drives the app through the Chrome DevTools Protocol.

You add it to Cursor or Claude and ask in normal language. The client shows the agent every tool and its arguments. This page is the map of what those tools are for.

Changelog

Full history, including 1.6 and 1.5, is in CHANGELOG.md on GitHub. The same file ships in the npm package.

What you can ask it to do

Examples you can type:

• “Start D:/apps/my-app and tell me if the window is blank.”
• “Click Go, type Ada in the name field, and tell me if the status says saved.”
• “What failed on the network, and what did the response body say?”
• “Attach to the Electron app I already launched and screenshot it.”
• “Profile the settings screen, then save a heap snapshot.”

Install

Cursor and Claude should spawn the process. Running it in a terminal looks idle because it is waiting on stdio.

{
  "mcpServers": {
    "electron-debug": {
      "command": "npx",
      "args": ["-y", "electron-debug-mcp"],
      "env": {
        "ELECTRON_MCP_NO_SANDBOX": "1"
      }
    }
  }
}

Claude Desktop config files:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

From a clone, build once and point command at node with the absolute path to build/index.js. Templates live in the repo under examples/.

npm install
npm run build

electron is an optional dependency. Attach-only installs can use npm install --omit=optional. On Windows, if npm skips postinstall, run scripts/fix-electron.cmd. Requires Node 18 or newer.

How a session works

start_app launches your app with a DevTools port. find_apps reads Electron PIDs from the process list. discover_apps probes local ports. attach and attach_by_pid join an app that is already running.

The reply includes an id, usually electron-…. Later calls pass that id as processId.

stop_app kills a process this server started. On an attached session it only detaches. Either way the session leaves list_apps.

Pass inspectMain: true when the bug is in the main process. That opens a separate --inspect port. These tools need it: evaluate_main, main_state, ipc_tap, get_ipc_log, webcontents_topology, open_deep_link, focus_window, set_window_bounds, get_clipboard, set_clipboard, get_downloads, set_permission.

Page targets keep console, network, and audit events buffered between calls.

Start, look, act, check

{ "appPath": "/path/to/your-app", "inspectMain": true }

start_app returns id. Use it as processId.

vision returns a screenshot plus the page URL, console errors, and failed requests. snapshot returns the accessibility tree when a CSS selector is the wrong handle.

{ "processId": "electron-…", "name": "Submit", "role": "button" }

{ "processId": "electron-…", "textIncludes": "Saved", "maxConsoleErrors": 0 }

click_ax clicks the button named Submit. assert_ui returns pass: true or pass: false with one line per check. A failed check is not a crashed tool.

get_network_log lists requests. get_response_body needs a finished requestId from that log. network_stub fulfills or fails a URL pattern. stop_app removes the session.

doctor is the first call when the environment itself is suspect: missing Electron binary, no display, sandbox flags.

Tools

Connect

See

Act

Page state

Network

Profile

Main process

Prompts

Resources

Configuration

$env:ELECTRON_MCP_ALLOWED_ROOTS="D:\apps;D:\src"

Screenshot and trace writes are rejected under credential and system roots (~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.docker, /etc, /proc, /usr, /root, C:\Windows, C:\Program Files, and similar). Existing ancestors are resolved so macOS /tmp → /private/tmp still matches.

Security

This is a local debugger. It can start binaries, evaluate JavaScript, and read page content, cookies, storage, and network bodies. Set ELECTRON_MCP_ALLOWED_ROOTS on a shared machine. Attach only to apps you trust. Do not expose stdio on an open network. Buffers and exported traces can contain secrets from the app under test.

Troubleshooting

Develop

npm test

That builds, runs unit tests, and runs the MCP smoke test against fixtures/minimal-electron-app. CI runs the same suite on Ubuntu (Xvfb), Windows, and macOS.

src/index.ts wires the server and the stdio transport. src/tools/ registers each group: connect, page, network, profile, main, prompts, and resources. src/process-manager.ts owns sessions and DevTools. src/power-tools.ts holds the higher-level helpers. Logs go to stderr so stdout stays clean for JSON-RPC.

The npm package contains build/, assets/, this README, LICENSE, and CHANGELOG.md.

License

ISC