🚀 Electron Debug MCP Server

Electron Debug MCP

AI コーディングエージェントに、本物の Chrome DevTools Protocol の力を。
Cursor、Claude、自律型エージェントに、Electron デスクトップアプリ内を見て、操作し、実行時に深く調査する力を与えます。

クイックスタート • 強力な機能 • ツール一覧 • 活用例 • リソースとプロンプト • 変更履歴 • トラブルシューティング

---

🌟 Electron Debug MCP を使う理由

多くの AI コーディングエージェントは、デスクトップアプリケーションの扱いに苦労します。ソースコードは編集できても、結果のウィンドウを見たり、ボタンをクリックしたり、コンソールエラーを読み取ったり、表面化しないメインプロセスのクラッシュを診断したりできません。

Electron Debug MCP は、Chrome DevTools Protocol（CDP）とNode インスペクターを通じて、エージェントを Electron の実行環境に直接接続し、視覚的な操作、対話、診断を完全に自律して行えるようにします。

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)"]

✨ 強力な機能

⚡ クイックスタート

1. MCP クライアントを設定する

🚀 Cursor の場合（~/.cursor/mcp.json または .cursor/mcp.json）

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

💬 Claude Desktop の場合（claude_desktop_config.json）

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

ヒント

ローカルで開発していますか？ npm run build を実行し、"command": "node" と "args": ["/path/to/electron-mcp-server/build/index.js"] を設定してください。

🛠️ ツール一覧（111 個）

すべてのツールで processId は任意です。実行中のアプリが 1 つだけの場合、自動的にアクティブなプロセスを特定します。

🚀 ライフサイクルと接続（8 個）

👁️ 表示と視覚的な検査（8 個）

🖱️ 操作と UI の自動化（13）

📄 ページ状態とナビゲーション（20）

🌐 ネットワークとダウンロード（12）

📈 パフォーマンス、プロファイリング、デバッガー（16）

🛡️ メインプロセス、ネイティブモック、メニュー、セキュリティ（23）

🩺 メタデータと診断（11）

📦 リソースとプロンプト

📡 標準 MCP リソース

標準 MCP リソースを通じて、リアルタイムの状態とエクスポートされた成果物を直接公開します。

• electron://server — サーバーのステータス、バージョン、ホスト環境。
• electron://info — アクティブなプロセス ID、ターゲットの内訳、最近のエラー数。
• electron://targets — 接続中のすべてのプロセスにおける、ライブ CDP ターゲット。
• electron://artifacts — エクスポートされたすべてのスクリーンショット、トレース、ヒープスナップショット、HAR のインデックス。
• electron://artifact/{id} — ID を指定して、エクスポートされた成果物を取得します。
• electron://process/{id} · electron://logs/{id} · electron://console/{id} · electron://cdp/{proc}/{target}

💬 組み込み MCP プロンプト

ワンクリックで呼び出せる、対話型デバッグレシピです。

• debug_blank_window — 白画面または空白のレンダラーを体系的に診断します。
• find_renderer_exception — 未処理の例外を特定し、監査を調査して、ソーススタックを解決します。
• ui_smoke_check — エンドツーエンドの UI 検証：待機、操作、アサーションを行います。
• attach_and_screenshot — ローカルアプリを検出してアタッチし、画面の状態をキャプチャします。
• vision_then_act — 視覚優先のエージェントループ：確認し、セマンティックターゲットを特定して、操作し、検証します。
• ax_then_assert — アクセシビリティ優先の操作ループ：アクセシブルな名前で特定し、状態をアサートします。

📚 エージェントレシピ

1. 視覚 → 操作 → 検証ループ

// 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. 自動化フォームでのシークレットのマスキング

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

メモ

process.env.MY_APP_API_KEY を解決し、CDP 経由で挿入して、typed: "[REDACTED]" を返します。その後のすべてのログ、コンソールイベント、HAR ファイルからシークレットを自動的にサニタイズします。

3. 自動セキュリティ監査

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

webPreferences と Electron バイナリのフューズについて、チェックリストのスコア（0～100）、レターグレード（A～F）、実行可能な修正ガイダンスを返します。

4. IPC コントラクトの推論

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

実行時の通信を観測し、プリロード API 用のすぐに使える TypeScript 定義を直接生成します。

5. マルチステップワークフローエンジンと Playwright Codegen（run_script）

変数の補間、条件分岐、リトライ、アサーションチェック、コード生成を使用して、複雑な複数アクションの自動化を 1 回の MCP ラウンドトリップでサーバー側から実行します。

{
  "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"
  }
}

機能とオプション

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 ロケーターと Set-of-Marks による視覚プロンプト

コンパクトな ref（e1、e2）でアクセシビリティターゲットを調べ、壊れやすい CSS セレクターを使わずに操作します。

// 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. ネイティブ Electron API のモック（ダイアログ、Shell、クリップボード）

自動テストの実行中に、OS のファイルダイアログ、外部 URL のオープン、または更新確認をバイパスします：

// 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. ネイティブアプリケーションメニューとアクセラレーターのトリガー

ネイティブ OS メニューとグローバルキーボードショートカットを自動化します：

// 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. プロセスのヘルスウォッチドッグとクラッシュ診断

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

リアルタイムのステータス（"healthy"、"unresponsive"、または "crashed"）を返し、OOM による終了、子プロセスの障害、ウィンドウのハング、メモリ指標を追跡します。

10. ストレージ状態のスナップショットと認証の再生

セッション状態全体（cookies、localStorage、sessionStorage）を Playwright 互換のストレージ状態アーティファクトに保存し、テスト間でログインフローを繰り返さずに済むようにします：

// 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. ワンショットのバグ再現バンドルと Issue 生成（repro_bundle）

ビューポートのスクリーンショット、完全な MHTML DOM アーカイブ、HAR ネットワークリプレイ、ソースマップ付きコンソールエラー、stderr の末尾、ヘルスメトリクス、GitHub にそのまま使える Markdown の Issue レポートを含む、完全な自己完結型の zip アーカイブを 1 回のターンでパッケージ化します：

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

artifactUri: "electron://artifact/..."、保存先パス、GitHub の Issue または Jira にそのまま貼り付けられる完全な Markdown の概要を返します。

12. スマートな複数フィールド対応のアクセシブルなシークレットフォームソルバー（fill_form）

キーと値の辞書、または構造化されたフィールド仕様から、1 回のツール呼び出しで複数入力フォーム全体に入力します：

{
  "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"
    }
  }
}

アクセシビリティツリーのラベル、ARIA 属性、プレースホルダー、または参照（e1）を使ってフィールドを解決し、シークレットを安全に処理し、ドロップダウンの選択肢を選択し、チェックボックスを切り替え、送信ボタンをクリックして、送信後の UI アサーションを検証します。

13. ネットワーク障害とレジリエンスのスコアカード（offline_resilience_check）

操作中に現実世界のネットワーク障害条件（オフライン、遅延、HTTP 500）をシミュレートし、アプリのヘルス状態とエラーの急増を監視して、ネットワークを復旧し、エグゼクティブ向けのレジリエンス評価（A～F）を算出します：

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

14. レスポンシブテーマとビューポートのマトリックススイープ（responsive_theme_matrix）

カラースキーム（light、dark）やビューポートサイズに応じたレイアウトの適応を監査し、水平スクロールバーのはみ出し（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 セキュリティとクラッシュ耐性強化のファザー（ipc_fuzz_and_verify）

悪意のあるペイロードや不正なペイロード（null、プロトタイプ汚染、パストラバーサル、過大なバッファー）に対するレンダラーからメインへの IPC 通信を強化し、プロセスがクラッシュに耐えられることを検証します：

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

📋 変更履歴とリリース

ヒント

過去のリリースノート、API 移行に関する注意事項、依存関係の更新はすべて、CHANGELOG.md で管理しています。

🧯 トラブルシューティング

📜 開発と検証

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

📄 ライセンス

ISC © Electron Debug MCP コントリビューター

_{Electron の内部を見て操作する必要がある自律型エージェントのために構築されています。}