debugtron-mcp

An MCP server that lets AI agents debug installed Electron apps end-to-end: discover apps, launch them with debug ports, evaluate JavaScript in the main process and renderer pages, capture console/IPC/network traffic, take screenshots, simulate input, profile CPU and heap, set breakpoints, read script sources, and inspect workers.

App discovery and launch adapters are vendored from debugtron (MIT); the debugging surface (Chrome DevTools Protocol + Node inspector) is exposed as 40+ MCP tools.

Requirements

• Node.js >= 22
• macOS / Windows / Linux (remote Android debugging via adb is supported by the underlying adapters but currently limited to page-level CDP)

Build

yarn install
yarn build        # outputs dist/index.js (single-file ESM bundle)
yarn typecheck    # optional

Usage

Register with your MCP client over stdio. For Claude Code:

claude mcp add debugtron -- node /path/to/debugtron-mcp/dist/index.js

Or explore interactively with the MCP inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Typical agent session

1. list_apps — discover installed Electron apps
2. launch_app — launch one (by appId or direct exePath), get a sessionId
3. list_pages — find renderer windows/webviews/workers (retry until they appear)
4. evaluate_in_main / evaluate_in_renderer — run JS in either process
5. get_console_logs / get_network_log / get_process_logs — observe behavior
6. get_response_body / get_cookies / get_local_storage — inspect network/state
7. screenshot / click / type / navigate — drive the UI
8. monitor_ipc + get_ipc_log — capture IPC traffic
9. monitor_events + get_event_log — capture lifecycle/navigation/crash events
10. list_scripts + get_script_source — read app bundles for static analysis
11. set_breakpoint / evaluate_on_call_frame / step_over — debug at source level
12. get_heap_snapshot / start_cpu_profile — deep performance diagnostics
13. list_workers / evaluate_in_worker — debug service/shared/dedicated workers
14. stop_session — terminate the app and clean up

Tools

Sessions & discovery

Tool	Description
list_apps	Discover installed Electron apps (targetId?, refresh?)
launch_app	Launch an app with --inspect + --remote-debugging-port (appId? or exePath?, env?, cwd?)
stop_session	Close CDP connections and terminate the app (idempotent)
list_sessions	List active sessions with status and ports
list_pages	List renderer targets: pages, webviews, workers
get_process_logs	App process stdout/stderr (works after exit)

Execution & observation

Tool	Description
evaluate_in_main	Run JS in the Electron main process (Node inspector)
evaluate_in_renderer	Run JS in a renderer page (CDP Runtime.evaluate)
get_console_logs	Console messages + uncaught exceptions from main and pages
get_network_log	Network requests captured per page (includes requestId)
get_response_body	Get the response body of a captured request by requestId
get_cookies	Read all cookies from the browser network stack (incl HttpOnly)
get_local_storage	Read localStorage or sessionStorage entries
get_app_info	Electron/Chromium/Node versions, app paths, BrowserWindow list
get_process_metrics	Per-process CPU% and memory (app.getAppMetrics)

Page control & DOM

Tool	Description
navigate / reload	Page navigation (waits for load event, non-fatal)
screenshot	PNG/JPEG screenshot returned as MCP image content
get_dom_snapshot	outerHTML of the document or a selector (truncatable)
query_selector	Element tag/text/attributes/bounding rect by CSS selector
click / type	Input simulation by selector or coordinates (unicode-safe)
get_performance_metrics	Renderer metrics: JS heap, DOM nodes, layout counts

Electron-specific

Tool	Description
monitor_ipc / get_ipc_log	Capture IPC traffic (ipcMain send/invoke, webContents.send)
monitor_events / get_event_log	Capture lifecycle events (crashes, unresponsive, navigation, window creation)

Debugging & profiling

Tool	Description
list_scripts	List parsed scripts (filter by URL substring)
get_script_source	Read script source by scriptId (for static analysis of app.asar bundles)
set_breakpoint / remove_breakpoint / list_breakpoints	Breakpoints by script URL or regex, main or renderer
pause / resume / get_paused_state	Execution control and paused call-stack inspection
evaluate_on_call_frame	Evaluate in a paused frame context (access local variables)
step_over / step_into / step_out	Single-step execution
get_heap_snapshot	V8 heap snapshot written to a .heapsnapshot file
start_cpu_profile / stop_cpu_profile	CPU profile to .cpuprofile + hottest-functions summary

Workers

Tool	Description
list_workers	List service workers, shared workers, dedicated workers (Target domain)
evaluate_in_worker	Run JS in a worker target via the flatten protocol

Heap snapshots and CPU profiles are written to files (default: system temp dir, override with filePath) and can be opened in Chrome DevTools.

Notes & limitations

• Single-instance lock: apps using requestSingleInstanceLock (e.g. VS Code) must be fully closed before launch_app; otherwise the second instance forwards to the running one and the debug flags are dropped. The tool error message tells you when this happens.
• Pages appear asynchronously: retry list_pages for a few seconds after launch.
• monitor_ipc captures send messages on ipcMain at any time, but invoke handlers only if they were registered after monitoring started (Electron dispatches handle() internally, not through the emitter).
• Breakpoints on inline scripts (e.g. inside data: URLs) don't bind; use them on real script files (file://.../app.asar/..., http(s)://...).
• Workers are discovered via the browser-level Target domain (separate from /json). Some older Electron versions may not expose all worker types.
• Diagnostics are written to stderr; stdout is reserved for the MCP protocol.

Acknowledgements

• Target discovery/launch adapters (src/targets/) and the AppInfo type are vendored from debugtron by Rongjian Zhang (MIT License).

License

MIT