🚀 Electron Debug MCP Server

Electron Debug MCP

Real Chrome DevTools Protocol superpowers for AI coding agents.
Give Cursor, Claude & autonomous agents eyes, hands, and deep runtime inspection inside Electron desktop applications.

Quick Start • Superpowers • Tool Matrix • Recipes • Resources & Prompts • Changelog • Troubleshooting

---

🌟 Why Electron Debug MCP?

Most AI coding agents struggle with desktop applications: they can edit source code, but they cannot see the resulting window, click buttons, read console errors, or diagnose silent main-process crashes.

Electron Debug MCP bridges your agent directly into your Electron runtime via the Chrome DevTools Protocol (CDP) and Node inspector, unlocking full visual, interactive, and diagnostic autonomy.

flowchart LR
    A["🤖 AI Agent (Cursor / Claude)"] <-->|"stdio JSON-RPC"| B["⚡ Electron Debug MCP"]
    B <-->|"CDP (WebSocket)"| C["🖼️ Renderer Windows\n(DOM · AXTree · Network · V8)"]
    B <-->|"Node Inspector / V8"| D["⚙️ Main Process\n(IPC · WebContents · Windows · Fuses)"]

✨ Key Superpowers

⚡ Quick Start

1. Configure Your MCP Client

🚀 In Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

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

💬 In Claude Desktop (claude_desktop_config.json)

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

Tip

Developing locally? Run npm run build and configure "command": "node" with "args": ["/path/to/electron-mcp-server/build/index.js"].

🛠️ Tool Matrix (111 Tools)

All tools accept an optional processId. When only one app is running, it automatically resolves to the active process.

🚀 Lifecycle & Connection (8)

👁️ See & Visual Inspection (8)

🖱️ Act & UI Automation (13)

📄 Page State & Navigation (20)

🌐 Network & Downloads (12)

📈 Performance, Profiling & Debugger (16)

🛡️ Main Process, Native Mocks, Menus & Security (23)

🩺 Meta & Diagnostics (11)

📦 Resources & Prompts

📡 Standard MCP Resources

Expose real-time state and exported artifacts directly via standard MCP resources:

• electron://server — Server status, version, and host environment.
• electron://info — Active process IDs, target breakdown, and recent error counts.
• electron://targets — Live CDP targets across all connected processes.
• electron://artifacts — Index of all exported screenshots, traces, heap snapshots, and HARs.
• electron://artifact/{id} — Fetch an exported artifact by its ID.
• electron://process/{id} · electron://logs/{id} · electron://console/{id} · electron://cdp/{proc}/{target}

💬 Built-in MCP Prompts

Interactive debugging recipes ready for one-click invocation:

• debug_blank_window — Systematically diagnose white/blank renderers.
• find_renderer_exception — Isolate unhandled exceptions, inspect audits, and resolve source stacks.
• ui_smoke_check — End-to-end UI verification: wait, interact, and assert.
• attach_and_screenshot — Discover local apps, attach, and capture visual status.
• vision_then_act — Visual-first agent loop: see, locate semantic target, act, and verify.
• ax_then_assert — Accessibility-first action loop: locate by accessible name and assert state.

📚 Agent Recipes

1. Vision → Act → Verify Loop

// Step 1: Look at the screen and check for errors
{ "name": "vision", "arguments": {} }

// Step 2: Act and verify in a single turn (captures failure screenshot if assertion fails)
{
  "name": "act_and_verify",
  "arguments": {
    "action": { "type": "click_ax", "name": "Sign In" },
    "assertion": { "textIncludes": "Welcome back" }
  }
}

2. Secret Redaction in Automation Forms

{
  "name": "type_text",
  "arguments": {
    "selector": "#api-key",
    "text": "{{secret:MY_APP_API_KEY}}"
  }
}

Note

Resolves process.env.MY_APP_API_KEY, inserts it via CDP, returns typed: "[REDACTED]", and automatically sanitizes the secret from all subsequent logs, console events, and HAR files.

3. Automated Security Audit

{ "name": "electron_security_audit", "arguments": {} }

Returns checklist score (0–100), letter grade (A–F), and actionable remediation guidance for webPreferences and Electron binary fuses.

4. IPC Contract Inference

// 1. Arm tap -> 2. Run app interactions -> 3. Infer TypeScript contracts
{ "name": "ipc_schema_inference", "arguments": {} }

Generates ready-to-use TypeScript definitions for your preload APIs directly from observed runtime communication.

5. Multi-Step Workflow Engine & Playwright Codegen (run_script)

Execute complex, multi-action automations server-side in a single MCP roundtrip with variable interpolation, conditional branching, retries, assertion checks, and code generation.

{
  "name": "run_script",
  "arguments": {
    "vars": {
      "targetWorkspace": "workspace-alpha",
      "expectedItems": 3
    },
    "steps": [
      {
        "id": "authenticate",
        "tool": "type_text",
        "args": {
          "selector": "input#token",
          "text": "{{secret:APP_API_TOKEN}}"
        },
        "expect": { "status": "success" }
      },
      {
        "id": "switch_workspace",
        "tool": "click",
        "args": { "selector": "button.workspace-switch" },
        "retry": { "retries": 3, "delayMs": 250 }
      },
      {
        "id": "check_banner",
        "tool": "eval_js",
        "args": { "expression": "Boolean(document.querySelector('.promo-modal'))" }
      },
      {
        "id": "dismiss_banner",
        "if": "{{steps.check_banner.result.value}} == true",
        "tool": "click",
        "args": { "selector": ".promo-modal .close-btn" }
      },
      {
        "id": "verify_workspace_state",
        "tool": "eval_js",
        "args": {
          "expression": "({ active: document.querySelector('#current-ws').textContent.trim(), count: document.querySelectorAll('.item').length })"
        },
        "expect": {
          "js": "result.value.active === 'workspace-alpha' && result.value.count >= 3"
        }
      }
    ],
    "exportAs": "playwright"
  }
}

Capabilities & Options

import { test, expect, _electron as electron } from "@playwright/test";

test("executed script workflow", async () => {
  const electronApp = await electron.launch({ args: ["."] });
  const window = await electronApp.firstWindow();

  // Step: authenticate
  await window.locator("input#token").fill(process.env.APP_API_TOKEN || "");

  // Step: switch_workspace
  await window.locator("button.workspace-switch").click();

  // Step: dismiss_banner
  await window.locator(".promo-modal .close-btn").click();

  // Step: verify_workspace_state
  const evalResult = await window.evaluate("({ active: document.querySelector('#current-ws').textContent.trim(), count: document.querySelectorAll('.item').length })");
  expect(evalResult).toBeDefined();

  await electronApp.close();
});

6. Ref Locators & Set-of-Marks Visual Prompting

Inspect accessibility targets with compact refs (e1, e2) and drive interactions without fragile CSS selectors:

// 1. Take snapshot with Set-of-Marks badges in the screenshot
{ "name": "vision", "arguments": { "markElements": true } }

// 2. Click directly by ref token
{ "name": "click", "arguments": { "ref": "e3" } }

// 3. Type text into ref
{ "name": "type_text", "arguments": { "ref": "e4", "text": "Hello Desktop!" } }

7. Native Electron API Mocking (Dialogs, Shell, Clipboard)

Bypass OS file dialogs, external URL opens, or update checks during automated test runs:

// 1. Mock dialog.showOpenDialog to return test fixtures
{
  "name": "mock_electron_api",
  "arguments": {
    "module": "dialog",
    "method": "showOpenDialog",
    "returns": { "canceled": false, "filePaths": ["/fixtures/document.pdf"] }
  }
}

// 2. Mock shell.openExternal
{
  "name": "mock_electron_api",
  "arguments": {
    "module": "shell",
    "method": "openExternal",
    "returns": true
  }
}

// 3. Inspect tracked invocations
{ "name": "get_mock_calls", "arguments": { "module": "shell", "method": "openExternal" } }

// 4. Restore original implementation
{ "name": "restore_electron_mocks", "arguments": { "module": "shell", "method": "openExternal" } }

8. Native Application Menu & Accelerator Trigger

Automate native OS menus and global keyboard shortcuts:

// 1. Inspect the full native menu tree
{ "name": "get_application_menu", "arguments": {} }

// 2. Click menu item by path or role
{ "name": "click_menu_item", "arguments": { "path": "File > Save" } }

// 3. Dispatch an Electron accelerator directly
{ "name": "trigger_shortcut", "arguments": { "accelerator": "CommandOrControl+Shift+P" } }

9. Process Health Watchdog & Crash Diagnostics

{ "name": "get_process_health", "arguments": {} }

Returns real-time status ("healthy", "unresponsive", or "crashed"), tracking OOM terminations, child process failures, window hangs, and memory metrics.

10. Storage State Snapshot & Auth Replay

Save full session state (cookies, localStorage, sessionStorage) into Playwright-compatible storage state artifacts to bypass repeated login flows across tests:

// 1. Export storage state to an artifact
{ "name": "save_storage_state", "arguments": {} }

// 2. Restore state into any new Electron session
{
  "name": "load_storage_state",
  "arguments": {
    "state": { "cookies": [...], "origins": [...] }
  }
}

11. One-Shot Bug Repro Bundle & Issue Generator (repro_bundle)

Package a complete, self-contained zip archive containing viewport screenshot, full MHTML DOM archive, HAR network replay, source-mapped console errors, stderr tail, health metrics, and a GitHub-ready Markdown issue report in one turn:

{
  "name": "repro_bundle",
  "arguments": {
    "notes": "Regression on checkout flow after OAuth upgrade"
  }
}

Returns artifactUri: "electron://artifact/...", destination path, and the complete markdown summary ready to paste into GitHub issues or Jira.

12. Smart Multi-Field Accessible & Secret Form Solver (fill_form)

Fill complete multi-input forms in a single tool call from either a key-value dictionary or structured field specs:

{
  "name": "fill_form",
  "arguments": {
    "fields": {
      "Username or Email": "[email protected]",
      "Password": "{{secret:APP_PASSWORD}}",
      "Environment": "Staging",
      "Remember Me": true
    },
    "submit": true,
    "expect": {
      "textIncludes": "Welcome back"
    }
  }
}

Resolves fields via accessibility tree labels, ARIA attributes, placeholders, or refs (e1), resolves secrets securely, selects dropdown options, toggles checkboxes, clicks submit, and verifies post-submit UI assertions.

13. Network Chaos & Resilience Scorecard (offline_resilience_check)

Simulate real-world network failure conditions (offline, latency, or HTTP 500) during interaction, monitor app health and error bursts, restore network, and compute an executive Resilience Grade (A–F):

{
  "name": "offline_resilience_check",
  "arguments": {
    "faultType": "offline",
    "durationMs": 1500,
    "action": { "type": "click", "selector": "#save-btn" }
  }
}

14. Responsive Theme & Viewport Matrix Sweep (responsive_theme_matrix)

Audit how layouts adapt across color schemes (light, dark) and viewport sizes, catching horizontal scrollbar leaks (scrollWidth > innerWidth):

{
  "name": "responsive_theme_matrix",
  "arguments": {
    "themes": ["light", "dark"],
    "viewports": [
      { "width": 800, "height": 600, "name": "compact" },
      { "width": 1280, "height": 800, "name": "desktop" }
    ]
  }
}

15. IPC Security & Crash Hardening Fuzzer (ipc_fuzz_and_verify)

Harden renderer-to-main IPC communication against malicious or malformed payloads (null, prototype pollution, path traversal, oversized buffers) and verify process crash resistance:

{
  "name": "ipc_fuzz_and_verify",
  "arguments": {
    "iterations": 6
  }
}

📋 Changelog & Releases

Tip

Complete historical release notes, API migration notes, and dependency updates are tracked in CHANGELOG.md.

🧯 Troubleshooting

📜 Development & Verification

npm test            # Run build, 140 unit tests, and full 111-tool smoke suite
npm run doctor      # Verify environment health and port binding
npm run sync:readme # Automatically synchronize badge counts with registered tools

📄 License

ISC © Electron Debug MCP contributors

_{Built for autonomous agents that need eyes — and hands — inside Electron.}