@iamvinitk/electron-mcp

MCP server for interacting with and debugging an Electron app. Spawns (or attaches to) an Electron process with the Chrome DevTools Protocol on the renderer and the Node inspector on the main process, then exposes ~20 tools for driving / inspecting both sides.

Works with any Electron or Electron Forge project.

Install

Run it on demand with npx (no install needed):

npx -y @iamvinitk/electron-mcp

…or install the electron-mcp binary globally:

npm i -g @iamvinitk/electron-mcp
electron-mcp

Use it from an MCP client

The server speaks MCP over stdio — point any MCP client at it. For a typical mcpServers config:

{
  "mcpServers": {
    "electron": {
      "command": "npx",
      "args": ["-y", "@iamvinitk/electron-mcp"]
    }
  }
}

(To run from a local clone instead, npm install && npm run build, then point your client's command/args at node /path/to/build/index.js.)

Tools

Lifecycle

Tool	Purpose
launch_via_npm	Spawn via npm run <script> (electron-forge dev).
launch_app	Spawn the electron binary directly (for packaged/test builds).
attach_app	Register an already-running Electron instance.
stop_app	Close CDP clients, kill spawned process, drop the session.
list_apps	Snapshot every active session (pid, ports, status, uptime).
ping_inspector	Zero-cost sanity check that the Node inspector is reachable.

Window automation

Tool	Purpose
list_windows	Enumerate renderer CDP targets. Skips devtools:// pages.
evaluate	Run JS in the renderer via Runtime.evaluate.
navigate	Page-navigate the renderer.
screenshot	Capture a PNG/JPEG via Page.captureScreenshot.

Logs & network

Tool	Purpose
get_main_logs	Read captured stdout/stderr from the spawned process.
get_console_messages	Read renderer console.* output and exceptions.
get_network_requests	Read renderer fetch/XHR activity (e.g. the app's API calls).
clear_logs	Wipe one or more ring buffers — useful before recording.

IPC

Tool	Purpose
list_electron_api_methods	Object.keys(window.electronAPI).
invoke_electron_api	Call any preload-exposed IPC method directly.
enable_ipc_logging	Inject a proxy that captures every IPC call the renderer makes.
get_ipc_log	Drain + read the captured IPC events.

Main-process state

Tool	Purpose
get_app_paths	app.getPath(...), app.isPackaged, process.resourcesPath, versions.
read_user_data_file	Path-traversal-guarded read under app.getPath('userData').

Resources

URI	Purpose
electron://sessions	JSON list of every tracked session.
electron://session/{id}	Detailed snapshot of one session (windows, recent logs, buffer sizes).

Typical debug flow

1. launch_via_npm             →   id=electron-abcd1234
2. list_windows  id=...       →   pick the target id
3. evaluate     id=... expr=… →   probe renderer state
4. invoke_electron_api        →   test an IPC handler
5. get_main_logs / get_console_messages / get_network_requests
6. stop_app                   →   tear down

How it works

• Launch modes. launch_app invokes the electron binary with --remote-debugging-port=<N> --inspect=<N+?> <appPath>. launch_via_npm wraps npm run <script> and smuggles --inspect-electron through forge's flag plumbing (double -- separators), because forge only exposes main-process inspection that way.

• Two debug channels. Electron renderers are Chromium pages, so they speak CDP on --remote-debugging-port. The main process is Node, which speaks the (near-identical) Node inspector protocol on --inspect. Both use chrome-remote-interface; we keep per-session client caches so repeated tool calls don't reconnect.

• Log capture. Main-process stdout/stderr flow into a ring buffer on spawn. Renderer console, exceptions, and network events flow into separate ring buffers via CDP event subscribers set up the first time each target's client opens. enable_ipc_logging installs a Proxy over window.electronAPI so every IPC call the renderer makes (regardless of origin) is observable; re-injected on Page.frameNavigated.

• Stdin stays open. Electron-forge's start command interprets an EOF on its stdin as "the user left the interactive REPL" and shuts down the child Electron. We hold stdin open (never write to it) so forge keeps running as long as we want.

Limitations

• Packaged builds. If the app's Electron Forge config disables the EnableNodeCliInspectArguments fuse, that blocks --inspect at the fuse layer in packaged builds. Window automation and renderer-side tools still work against a packaged build if you pass --remote-debugging-port, but main-process tools (get_app_paths, read_user_data_file) need a non-fused dev build.

• Single-process model. One MCP server → any number of tracked sessions. Sessions don't persist across MCP restarts; restart the MCP server to refresh.

• macOS stdin quirk. Some terminal emulators (rare) block SIGINT delivery through npm's stdin pipe. If stop_app leaves a zombie forge process, pkill -f electron-forge is the backup.

Development

npm run watch         # tsc --watch
npm run typecheck     # tsc --noEmit

There are no unit tests in this package. Verification is end-to-end against a running Electron app.