Electron Viewer

@acertijosapps/electron-viewer

ブラウザーで Electron アプリをリアルタイムに表示するビューアーと、AI エージェントがアプリを操作できる MCP サーバーです。 Claude Code などの AI コーディングツールのブラウザーペイン向けに構築されています。あなたとエージェントが、同じアプリウィンドウをリアルタイムに見て操作できます。

• ライブ動画：WebSocket 経由で Chrome DevTools Protocol（CDP）の Page.startScreencast を使用します。アプリのウィンドウがほかのウィンドウに隠れているときや最小化されているときも、ストリーミングを続けます。
• 実際の入力：マウス移動、ホバー、クリック、ダブルクリック、右クリック、ドラッグ、ホイール操作、キーボード入力の完全なパススルーに対応しています（macOS の ⌘C/⌘V/⌘A、IME、音声入力を含む）。
• すべてのアプリとウィンドウ：ビューアーから electron . でプロジェクトを起動するか、--remote-debugging-port を指定して起動した任意のアプリに接続できます。ポート 9222～9231 のアプリは自動的に検出されます。
• メインプロセスにも対応：起動したアプリではメインプロセス（Node インスペクター）も公開されるため、エージェントはそこでコードを実行したり、実際のウィンドウのサイズ変更、DevTools の起動、ネイティブフレームのキャプチャを行ったりできます。
• ネイティブフレームのキャプチャ：ウィンドウの上に表示されるタイトルバー、コンテキストメニュー、ダイアログもキャプチャできます。
• MCP サーバー：同じ操作をツールとして提供するほか、レンダラープロセスとメインプロセスでの JavaScript 実行、クリック可能な座標付きのアクセシビリティツリー、コンソールログにも対応しています。
• アプリへの追加は不要：プリロードも依存関係もなく、コードの変更も不要です。

要件

• Node.js 18 以降。
• Electron アプリ。ビューアーから起動するには、プロジェクトの node_modules に electron が必要です（npm install --save-dev electron）。バイナリがまだダウンロードされていない場合、ビューアーが初回起動時にダウンロードします。
• macOS、Linux、Windows で動作します。

クイックスタート

Electron プロジェクトのフォルダーで実行します。

npx @acertijosapps/electron-viewer

http://localhost:8094 を開き、Launch をクリックします。ビューアーは空いているデバッグ用ポートで electron . を実行します（CDP は 9222 から、Node インスペクターは 9229 から）。ウィンドウへのディープリンク：?window=<target id>。

アプリを別のツール（Electron Forge、electron-vite、カスタムスクリプトなど）で起動する場合は、フラグを自分で渡せばビューアーがアプリを検出します。

electron --remote-debugging-port=9222 --inspect=9229 .

--inspect は省略可能です。指定しない場合、メインプロセスの機能（evaluate_main、フレームキャプチャ、実際のウィンドウのサイズ変更、アプリ内 DevTools）以外はすべて利用できます。別のポートに接続するには、ビューアーのフォームを使うか、--attach を指定します。

electron-viewer [options]        Start the viewer
electron-viewer mcp [options]    Start the MCP server on stdio

      --project <dir>      Project to launch with "electron ." (default: current folder)
  -p, --port <port>        Viewer port (default 8094, env PORT)
      --host <host>        Interface to bind (default 127.0.0.1, env HOST)
      --attach <port>      Attach at startup to an app on this CDP port
      --inspect <port>     With --attach: the app's main process inspector port
      --viewer-url <url>   Viewer the MCP talks to (default http://localhost:8094)

その他の環境変数：MAX_DIM（ストリーミングするフレームの長辺。デフォルトは 1920）、QUALITY（JPEG 品質。デフォルトは 80）、SCREENSHOT_MAX（MCP スクリーンショットの長辺。デフォルトは 1024）、CDP_PORT／INSPECT_PORT（スキャンおよび起動に使う最初のポート。デフォルトはそれぞれ 9222／9229）、ELECTRON_VIEWER_STATE_DIR（起動および接続したアプリの状態を保存する場所。デフォルトは ~/.cache/electron-viewer）。

AI エージェントで使用する（MCP）

Claude Code：

claude mcp add electron-viewer -- npx -y @acertijosapps/electron-viewer mcp

その他のMCPクライアント：

{
  "mcpServers": {
    "electron-viewer": {
      "command": "npx",
      "args": ["-y", "@acertijosapps/electron-viewer", "mcp"]
    }
  }
}

公式MCP Registryにも io.github.acertijosapps/electron-viewerとして掲載されています。

エージェントの操作を確認するには、ビューアー（npx @acertijosapps/electron-viewer）を起動したままにしてください。ビューアーが起動していなくても、MCPはCDPを介してアプリを直接操作します。どちらか一方が起動したアプリは、もう一方からも確認できます。

ツール	説明
list_windows	実行中のアプリ（メインプロセスに接続できる場合は main も表示）とそのウィンドウ
launch_app	プロジェクトで electron . を空いているデバッグポートで実行し、最初のウィンドウが表示されるまで待機
attach	CDPポートでアプリに接続。任意でインスペクターポートも指定可能
screenshot	ウィンドウのコンテンツのPNG画像。長辺は最大1024 px。frame: true を指定すると、ネイティブフレーム、メニュー、ダイアログも追加
click	左、右、または中央クリック。ダブルクリックは count: 2。修飾キーも任意で指定可能
drag	押下して段階的に移動し、離します。実際のドラッグ操作です
hover	クリックせずにマウスを移動
scroll	指定位置でマウスホイールを操作。差分はCSS px単位
type_text	フォーカスされた要素にテキストを挿入（あらゆるUnicode文字に対応）
press_key	Enter、Tab、Escape、矢印、F1～F12など、または任意の文字を修飾キーとともに入力
resize_window	コンテンツ領域のサイズを変更（メインプロセスがある場合は実際のウィンドウ、ない場合はエミュレート）
reload	ウィンドウのページを再読み込み
evaluate	ウィンドウのページでJavaScriptを実行し、値を返す
evaluate_main	メインプロセスでJavaScriptを実行。require('electron')を使用可能
get_accessibility_tree	ロール、名前、値、状態を取得。インタラクティブ要素には正規化された中心座標も含まれます
get_console_logs	レンダラーウィンドウとメインプロセスのコンソールメッセージおよび例外、または生の標準出力

座標はコンテンツのスクリーンショット上で 0–1 に正規化されます（x = pixel_x / image_width）。そのため、ウィンドウのサイズにかかわらず使用できます。ウィンドウが1つだけ開いている場合は、windowを省略できます。指定する場合は、list_windowsのターゲットID、またはウィンドウタイトルの一部を使用します。

Claude Codeのブラウザーペインで使用する

.claude/launch.jsonにビューアーを追加し、preview_start electron-viewerで開きます。

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "electron-viewer",
      "runtimeExecutable": "npx",
      "runtimeArgs": ["-y", "@acertijosapps/electron-viewer"],
      "port": 8094,
      "autoPort": false
    }
  ]
}

ネイティブフレームのキャプチャ

フレームボタン（または frame: true を指定した screenshot）を使うと、メインプロセスのdesktopCapturerでウィンドウの画面領域をキャプチャできます。タイトルバー、ネイティブのコンテキストメニュー、ウィンドウに重なったダイアログが、1秒間に数フレーム表示されます。ウィンドウを覆うその他のものも表示されますが、画面上部のmacOSメニューバーは含まれません。フレームモードでもコンテンツ上のクリックは機能しますが、ビューアーからタイトルバーやネイティブメニューをクリックすることはできません。

macOSでは、アプリに画面収録のアクセス許可が必要です（システム設定 › プライバシーとセキュリティ › 画面とシステムオーディオの収録）。electron .で起動したアプリの場合、対象はプロジェクトのnode_modules/electron/dist内にあるElectron.appです。エラーメッセージに正確なパスが表示されます。許可した後、アプリを再起動してください。

HTTP API

MCP はビューアーの API を使用しており、こちらから呼び出すこともできます。window（ターゲット ID またはタイトルの一部）はクエリ文字列またはリクエスト本文で指定します。ウィンドウが 1 つの場合は省略できます。サーバーは 127.0.0.1 のみで待ち受け、ローカルの Host とオリジンのみを受け付けます。また、POST リクエストには content-type: application/json が必須のため、他のウェブサイトからアプリを操作することはできません。

エンドポイント
GET /api/windows	[{ id, name, cdpPort, inspectPort, main, windows: [{ id, title, url }] }]
GET /api/project	ビューアーが起動するプロジェクトと、Electron がインストールされているかどうか
GET /api/screenshot?max=<px>&frame=1	PNG。ビューポートサイズは X-Viewport-Width / X-Viewport-Height に格納されます
GET /api/ax-tree?interactiveOnly=true	{ tree }
GET /api/logs?level=&source=&limit=	{ logs } または { stdout }
POST /api/launch	{ project? }
POST /api/attach	{ port, inspectPort? }
POST /api/click	{ x, y, button?, count?, modifiers? }
POST /api/drag	{ x1, y1, x2, y2, ms? }
POST /api/hover	{ x, y }
POST /api/scroll	{ x, y, dx, dy }
POST /api/text	{ text }
POST /api/key	{ key, modifiers? }
POST /api/resize	{ width, height }（0 × 0 にするとウィンドウサイズを復元します）
POST /api/reload	{ ignoreCache? }
POST /api/evaluate	{ expression }
POST /api/evaluate-main	{ expression, app? }
POST /api/devtools	DevTools の表示を切り替えます。メインプロセスがない場合は DevTools の url を返します

仕組み

• すべての処理は ws を使って CDP 経由で行われます。Playwright も Puppeteer も使用せず、アプリに何も注入しません。レンダラープロセスには --remote-debugging-port（ウィンドウごとに 1 つの page ターゲット）経由で接続し、メインプロセスには Node インスペクター（--inspect）経由で接続します。メインプロセスではコンソール API から require を利用できます。
• ウィンドウごとに 1 つのスクリーンキャストセッションを使用し、すべてのビューアータブで共有します。最後のタブが閉じると停止します。最後のフレームは、後から参加するユーザーのために保持されます。誰かが閲覧している間はフォーカスとページのライフサイクルをエミュレートするため、別のウィンドウに覆われたり最小化されたりしても描画を続けます。
• ビューアーからの入力は順番にキューへ追加され、マウスの移動はアニメーションフレームごとに 1 回へまとめられます。フォーカスは非表示のテキストエリアが保持します。キーは Input.dispatchKeyEvent で送信し、キーイベントなしで届いたテキスト（IME、音声入力）は Input.insertText で送信します。macOS では、通常これらを処理するネイティブメニューが CDP イベントを受け取らないため、⌘A、⌘C、⌘V、⌘X、⌘Z は編集コマンドとして送信されます。
• 各プロセスはウィンドウごと、メインプロセスごとに 1 つの接続を保持します。接続ではコンソールメッセージと例外も収集します（アプリごとに最新 1000 件）。
• 起動または接続したアプリは ~/.cache/electron-viewer に記録されるため、ビューアーと MCP から同じアプリを確認できます。起動したアプリはその場所に出力をログファイルとして書き込み、ビューアーまたは MCP が終了しても実行を続けます。

制限事項

• CDP で確認できるのはウェブコンテンツのみです。ネイティブ UI（タイトルバー、メニュー、ダイアログ、トレイ、通知）はフレームモードでのみ表示され、クリックできません。メインプロセスから操作するには evaluate_main を使用してください。
• 同期ダイアログ（dialog.showMessageBoxSync）はメインプロセスをブロックします。ダイアログが閉じるまで evaluate_main とフレームのキャプチャは待機します。
• WebContentsView はそれぞれ別の CDP ターゲットとなるため、独立したウィンドウとして一覧表示されます。<webview> タグは一覧表示されません。
• 音声には対応していません。
• フレームモードは毎秒数フレームで動作し、macOS では画面収録の許可が必要です。
• 起動前にビルドが必要なアプリ（Forge、electron-vite）はビューアーから起動できません。デバッグフラグを付けて起動すると、検出されます。

貢献

ブランチモデル（main · beta）、Conventional Commits、リリースについては CONTRIBUTING.md で説明しています。変更内容は CHANGELOG.md に記載されています。 変更を試すには、example/ のサンプルアプリを使用してください。

作者

AcertijosAppsが作成しました。他のライブラリについては、 acertijosapps.com/libreriasをご覧ください。

ご質問やご提案は、[email protected]までお寄せいただくか、 issueを作成してください。

ライセンス

MIT