Skip to main content
Glama
electron-mcp
by iamvinitk

@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

Related MCP server: electron-mcp-server

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.

Available Tools

20 tools
attach_appAttach to a running Electron appA

Register an already-running Electron instance as a debug session. The caller started the app with --remote-debugging-port=<debugPort> and optionally --inspect=<inspectPort>; this tool just probes those ports and stores them so the rest of the MCP can drive the app. Stopping the session with stop_app will NOT kill the underlying process — the caller owns its lifecycle.

Inputs: debugPort (required), name, inspectPort.

clear_logsClear one or more log buffersA

Wipe session ring buffers — useful to set a zero point before driving an action. Omit kinds to clear everything.

Inputs: id (required), kinds.

enable_ipc_loggingEnable IPC call logging in a rendererA

Inject a proxy over window.electronAPI that logs every method call (including those triggered by user actions) into the session's IPC ring buffer. Idempotent — safe to call multiple times; the installer no-ops if the proxy is already in place. Auto-reinstalls after Page.frameNavigated.

Inputs: id (required), target.

evaluateEvaluate JS in a rendererA

Run expression in the target renderer's main JS world via CDP Runtime.evaluate and return the result by value. Equivalent to typing the expression in the renderer's DevTools console. Use this for DOM inspection (document.title), state reads (localStorage.getItem('theme')), and any automation beyond what the click/type convenience tools cover.

Inputs: id (required), expression (required), target, awaitPromise, +1 more.

get_app_pathsRead Electron app paths + flagsA

Returns app.getPath(...) for the main paths (userData, temp, logs, downloads, documents, home), plus app.getAppPath(), app.isPackaged, process.resourcesPath, process.execPath, process.versions.electron. Requires the main-process Node inspector to be attached — if not, re-launch with a non-zero inspectPort.

Inputs: id (required).

get_console_messagesRead renderer console messagesA

Returns console.* output and unhandled exceptions from the renderer, captured via CDP Runtime. Use level to filter (e.g. error to see regressions without the React dev-mode info spam).

Inputs: id (required), grep, level, limit, +2 more.

get_ipc_logRead captured IPC call logA

Drain any pending renderer-side IPC events into the session buffer and return the matching entries. Requires enable_ipc_logging to have been called first. Each entry has the method name, JSON-serialised args/result, and duration in ms.

Inputs: id (required), limit, since, method, +1 more.

get_main_logsRead main-process stdout/stderrA

Returns the spawned process's captured log lines (stdout + stderr interleaved in order of receipt). These typically include the app's main-process startup lines and any backend/proxy output it prints when running packaged.

Inputs: id (required), grep, lines, since, +1 more.

get_network_requestsRead renderer network activityA

Returns captured CDP Network events (request / response / finished / failed). For a page load, multiple entries will share the same requestId — join them on that field to see the full request lifecycle. Default filter omits static assets so only XHR/fetch-style calls (e.g. API requests) surface; pass resourceType to override.

Inputs: id (required), kind, limit, since, +5 more.

invoke_electron_apiCall `window.electronAPI.<method>(...args)`A

Invoke any method exposed by the preload bridge. Returns the method's result (awaited if it's a promise). Use to test IPC handlers directly, e.g. invoke_electron_api({ method: 'dbCheckConnectivity' }) or invoke_electron_api({ method: 'getConfig', args: ['theme'] }).

Inputs: id (required), method (required), args, target.

launch_appLaunch Electron app (direct binary)A

Spawn an Electron application via the electron binary with --remote-debugging-port and --inspect flags set so the MCP can drive the renderer and main process. Use launch_via_npm instead for electron-forge projects; this tool is for apps that don't need the forge dev-server (or for packaged test builds).

Inputs: appPath (required), env, name, debugPort, +4 more.

launch_via_npmLaunch Electron app via `npm run`A

Spawn an Electron application by running an npm script (typically start in an electron-forge project). Forwards --inspect-electron through forge and --remote-debugging-port / --inspect through to Electron. Use this for an electron-forge workspace (e.g. apps/electron) where forge's dev server needs to come up first.

Inputs: cwd (required), env, name, debugPort, +4 more.

list_appsList debug sessionsA

Return a snapshot of every tracked session (launched + attached), with pid, ports, status, uptime, and tracked window count.

Inputs: no named parameters.

list_electron_api_methodsList `window.electronAPI.*` methodsA

Return the names of every method exposed on window.electronAPI in the chosen renderer. Useful to discover IPC channels before calling invoke_electron_api, or to verify a preload change actually exposed a new method.

Inputs: id (required), target.

list_windowsList CDP targets (BrowserWindows, webviews, workers)A

Enumerate every CDP target exposed by the session's renderer debug port. type: "page" entries correspond to BrowserWindows; pass their id to evaluate, navigate, or screenshot. Service/shared workers are included for completeness.

Inputs: id (required), includeWorkers.

ping_inspectorSanity check main inspector for a sessionA

Open the Node inspector on the session's main process and evaluate process.pid. Returns the pid on success; use this when get_app_paths times out to isolate whether the inspector is the problem.

Inputs: id (required).

read_user_data_fileRead a file under the app's userData dirA

Safely read a file relative to the session's app.getPath('userData') (e.g. config.json, api-logs/api.log). Path-traversal protected: paths are resolved against userData and rejected if they escape it. Returns the text content (up to the size cap) along with the resolved absolute path.

Inputs: id (required), relPath (required), maxBytes.

screenshotCapture a screenshot of a rendererA

Grab a PNG (or JPEG) of the target renderer via Page.captureScreenshot. Returns base64. Large payloads — encode sparingly and prefer fullPage: false (the default) for quick-look snapshots.

Inputs: id (required), format, target, quality, +1 more.

stop_appStop a debug sessionA

Close every CDP client tied to the session and, if the MCP launched the app, kill the underlying process. A no-op for already-stopped sessions, so safe to call unconditionally in cleanup flows.

Inputs: id (required), keepSession.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of Electron debugging (launching, attaching, logging, inspection, etc.), with clear boundaries even among similar logging tools. No two tools appear to overlap in purpose.

    Naming Consistency5/5

    All tool names use lowercase snake_case with a consistent verb_noun pattern (e.g., list_windows, get_app_paths, launch_app). There is no mixing of conventions, making the set predictable.

    Tool Count4/5

    20 tools is on the higher side, but each tool serves a specific need for a complex domain. Some tools like clear_logs and get_main_logs could arguably be combined, but the count is still reasonable.

    Completeness5/5

    The tools cover the full lifecycle of debugging an Electron app: launch/attach, inspect (renderer and main process), capture logs (console, IPC, network), navigate, screenshot, and stop. No obvious gaps for common tasks.

    Related MCP Connectors

    Related MCP Servers