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)

Related MCP server: @nebula-agents/electron-mcp

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

Execution & observation

Page control & DOM

Electron-specific

Debugging & profiling

Workers

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