electron-mcp
Provides tools for debugging and controlling an Electron application, including lifecycle management, window automation, console and network log capture, IPC logging, and main-process state inspection via Chrome DevTools Protocol and Node inspector.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@electron-mcp launch my Electron app via npm and list its windows"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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-mcpRelated 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 |
| Spawn via |
| Spawn the |
| Register an already-running Electron instance. |
| Close CDP clients, kill spawned process, drop the session. |
| Snapshot every active session (pid, ports, status, uptime). |
| Zero-cost sanity check that the Node inspector is reachable. |
Window automation
Tool | Purpose |
| Enumerate renderer CDP targets. Skips |
| Run JS in the renderer via |
| Page-navigate the renderer. |
| Capture a PNG/JPEG via |
Logs & network
Tool | Purpose |
| Read captured stdout/stderr from the spawned process. |
| Read renderer |
| Read renderer fetch/XHR activity (e.g. the app's API calls). |
| Wipe one or more ring buffers — useful before recording. |
IPC
Tool | Purpose |
|
|
| Call any preload-exposed IPC method directly. |
| Inject a proxy that captures every IPC call the renderer makes. |
| Drain + read the captured IPC events. |
Main-process state
Tool | Purpose |
|
|
| Path-traversal-guarded read under |
Resources
URI | Purpose |
| JSON list of every tracked session. |
| 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 downHow it works
Launch modes.
launch_appinvokes theelectronbinary with--remote-debugging-port=<N> --inspect=<N+?> <appPath>.launch_via_npmwrapsnpm run <script>and smuggles--inspect-electronthrough 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 usechrome-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_logginginstalls aProxyoverwindow.electronAPIso every IPC call the renderer makes (regardless of origin) is observable; re-injected onPage.frameNavigated.Stdin stays open. Electron-forge's
startcommand 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
EnableNodeCliInspectArgumentsfuse, that blocks--inspectat 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. Ifstop_appleaves a zombie forge process,pkill -f electron-forgeis the backup.
Development
npm run watch # tsc --watch
npm run typecheck # tsc --noEmitThere are no unit tests in this package. Verification is end-to-end against a running Electron app.
Available Tools
20 toolsattach_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
Scored across 20 tools
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.
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.
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.
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
MCP server to assist with JxBrowser development.
MCP server for interacting with the Supabase platform
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
The official Planning Center MCP server for interacting with your ministry's data.
Related MCP Servers
- AlicenseBqualityCmaintenanceA Model Context Protocol server that provides comprehensive Electron application automation, debugging, and observability capabilities through Chrome DevTools Protocol integration.41,473 npm71MIT
- AlicenseNot gradedqualityCmaintenanceEnables Electron app automation via Chrome DevTools Protocol (CDP), allowing MCP clients like Cursor or Claude Desktop to interact with Electron apps.4MIT
- AlicenseNot gradedqualityCmaintenanceEmbedded MCP server for Electron apps that exposes BrowserWindow surfaces and lets MCP clients drive renderers through Chrome DevTools Protocol.7 npmMIT
- AlicenseBqualityCmaintenanceElectron debugging MCP server for both renderer (via Chrome DevTools Protocol) and main process (via V8 Inspector Protocol), enabling automation, debugging, and network capture.315 npmMIT