Electron MCP Server

🚀 Electron MCP Server

Electron MCP Serverは、包括的なElectronアプリケーションの自動化、デバッグ、および監視機能を提供する強力なModel Context Protocol (MCP)サーバーです。Chrome DevTools Protocolとの統合により、AIを駆使した自動化でElectron開発ワークフローを強化します。

🚀 クイックスタート

まずは、Electron MCP Serverのデモを見てみましょう。

🎬 Vimeoで完全版デモを見る

AIを駆使したMCPコマンドでElectronアプリケーションを自動化するのがいかに簡単かを確認してください。

✨ 主な機能

🎮 アプリケーション制御と自動化

• 起動と管理：Electronアプリケーションの起動、停止、および監視をフルライフサイクルで制御します。
• インタラクティブ自動化：WebSocketを介して実行中のアプリケーションで直接JavaScriptコードを実行します。
• UIテスト：ボタンクリック、フォームインタラクション、およびユーザーワークフローを自動化します。
• プロセス管理：PIDを追跡し、リソース使用量を監視し、正常なシャットダウンを処理します。

📊 高度な監視機能

• スクリーンショット取得：PlaywrightとChrome DevTools Protocolを使用して、非侵入的なビジュアルスナップショットを取得します。
• リアルタイムログ：アプリケーションログ（メインプロセス、レンダラー、コンソール）をフィルタリングしてストリームします。
• ウィンドウ情報：詳細なウィンドウメタデータ、タイトル、URL、およびターゲット情報を取得します。
• システム監視：メモリ使用量、稼働時間、およびパフォーマンスメトリクスを追跡します。

🛠️ 開発生産性向上

• 汎用互換性：コードの変更を必要とせずに、すべてのElectronアプリで動作します。
• DevTools統合：Chrome DevTools Protocolを活用して強力なデバッグ機能を提供します。
• ビルド自動化：Windows、macOS、およびLinux用のクロスプラットフォームビルドを行います。
• 環境管理：クリーンな環境処理とデバッグポート構成を行います。

📦 インストール

VS Code統合（推奨）

VS CodeのMCP設定に以下を追加します。

{
  "mcp": {
    "servers": {
      "electron": {
        "command": "npx",
        "args": ["-y", "electron-mcp-server"]
      }
    }
  }
}

Claude Desktop統合

~/Library/Application Support/Claude/claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "electron": {
      "command": "npx",
      "args": ["-y", "electron-mcp-server"]
    }
  }
}

グローバルインストール

npm install -g electron-mcp-server

💻 使用例

スマートUIインタラクションワークフロー

// 1. まず、ページ構造を理解する
await send_command_to_electron({
  command: 'get_page_structure',
});

// 2. ボタンをテキストでクリックする（セレクタよりもはるかに信頼性が高い）
await send_command_to_electron({
  command: 'click_by_text',
  args: {
    text: 'Login', // テキスト、aria-label、またはタイトルに「Login」を含むボタンを見つける
  },
});

// 3. 入力フィールドをラベルまたはプレースホルダーテキストで埋める
await send_command_to_electron({
  command: 'fill_input',
  args: {
    text: 'username', // ラベルが「Username」またはプレースホルダーが「Enter username」の入力フィールドを見つける
    value: 'john.doe@example.com',
  },
});

await send_command_to_electron({
  command: 'fill_input',
  args: {
    text: 'password',
    value: 'secretpassword',
  },
});

// 4. ドロップダウンオプションを表示テキストで選択する
await send_command_to_electron({
  command: 'select_option',
  args: {
    text: 'country', // ラベルに「country」を含むセレクトボックスを見つける
    value: 'United States', // このテキストのオプションを選択する
  },
});

// 5. 結果を確認するためにスクリーンショットを撮る
await take_screenshot();

高度な要素検出

// 詳細情報を持つすべてのインタラクティブ要素を見つける
await send_command_to_electron({
  command: 'find_elements',
});

// これは、すべてのクリック可能な要素と入力フィールドの詳細情報を返します。
// {
//   "type": "clickable",
//   "text": "Submit Form",
//   "id": "submit-btn",
//   "className": "btn btn-primary",
//   "ariaLabel": "Submit the registration form",
//   "position": { "x": 100, "y": 200, "width": 120, "height": 40 },
//   "visible": true
// }

自動化UIテスト

// 開発モードでアプリを起動する
await launch_electron_app({
  appPath: '/path/to/app',
  devMode: true,
});

// スクリーンショットを撮る
await take_screenshot();

// プログラムでボタンをクリックする
await send_command_to_electron({
  command: 'eval',
  args: {
    code: "document.querySelector('#submit-btn').click()",
  },
});

// 結果を検証する
await send_command_to_electron({
  command: 'get_title',
});

開発デバッグ

// ウィンドウ情報を取得する
const windowInfo = await get_electron_window_info();

// アプリケーションデータを抽出する
await send_command_to_electron({
  command: 'eval',
  args: {
    code: 'JSON.stringify(window.appState, null, 2)',
  },
});

// ログを監視する
await read_electron_logs({
  logType: 'all',
  lines: 100,
});

パフォーマンス監視

// システム情報を取得する
await send_command_to_electron({
  command: 'eval',
  args: {
    code: '({memory: performance.memory, timing: performance.timing})',
  },
});

// ビジュアル回帰テストのために定期的にスクリーンショットを撮る
await take_screenshot({
  outputPath: '/tests/screenshots/current.png',
});

📚 ドキュメント

🎯 このサーバーの特長

AIを駆使した自動化により、Electron開発体験を変革します。

• 🔄 リアルタイムUI自動化：ボタンをクリックし、フォームを埋め、任意のElectronアプリとプログラムでインタラクションします。
• 📸 ビジュアルデバッグ：開発を中断することなく、スクリーンショットを撮り、アプリケーションの状態をキャプチャします。
• 🔍 深い検査：DOM要素、アプリケーションデータ、およびパフォーマンスメトリクスをリアルタイムで抽出します。
• ⚡ DevTools Protocol統合：任意のElectronアプリとの汎用互換性 - 修正不要。
• 🚀 開発監視：ログ、システム情報、およびアプリケーションの動作をシームレスに監視します。

🔒 セキュリティと構成

機能性と安全性をバランスさせるための構成可能なセキュリティレベル。

セキュリティレベル

• 🔒 STRICT：本番環境用の最大限のセキュリティ。
• ⚖️ BALANCED：安全なUIインタラクションを備えたデフォルトのセキュリティ（推奨）。
• 🔓 PERMISSIVE：信頼できる環境用のより多くの機能。
• 🛠️ DEVELOPMENT：開発/テスト用の最小限の制限。

安全なUIインタラクションコマンド

生のJavaScript evalの代わりに、これらの安全なコマンドを使用します。

// ✅ 安全なボタンクリック
{
  "command": "click_by_text",
  "args": { "text": "Create New Encyclopedia" }
}

// ✅ 安全な要素選択
{
  "command": "click_by_selector",
  "args": { "selector": "button[title='Create']" }
}

// ✅ 安全なキーボードショートカット
{
  "command": "send_keyboard_shortcut",
  "args": { "text": "Ctrl+N" }
}

// ✅ 安全なナビゲーション
{
  "command": "navigate_to_hash",
  "args": { "text": "create" }
}

詳細なセキュリティドキュメントについては、SECURITY_CONFIG.mdを参照してください。

🎯 適切なMCP使用ガイド

⚠️ 重要：引数構造

このMCPサーバーを使用する際の最も一般的な間違いは、send_command_to_electronツールの引数構造が正しくないことです。

❌ 誤り（「selector is empty」エラーの原因）：

{
  "command": "click_by_selector",
  "args": "button.submit-btn"  // ❌ 生の文字列 - 誤り！
}

✅ 正しい：

{
  "command": "click_by_selector",
  "args": {
    "selector": "button.submit-btn"  // ✅ セレクタプロパティを持つオブジェクト
  }
}

📋 コマンド引数リファレンス

🔄 推奨ワークフロー

1. 検査：get_page_structureまたはdebug_elementsで始めます。
2. ターゲット：特定のセレクタまたはテキストベースのターゲットを使用します。
3. インタラクション：正しい引数構造で適切なコマンドを使用します。
4. 検証：スクリーンショットを撮るか、ページの状態を確認します。

// ステップ1: ページを理解する
{
  "command": "get_page_structure"
}

// ステップ2: テキストを使用してボタンをクリックする（最も信頼性が高い）
{
  "command": "click_by_text",
  "args": {
    "text": "Create New Encyclopedia"
  }
}

// ステップ3: フォームフィールドを埋める
{
  "command": "fill_input",
  "args": {
    "placeholder": "Enter encyclopedia name",
    "value": "AI and Machine Learning"
  }
}

// ステップ4: セレクタで送信する
{
  "command": "click_by_selector",
  "args": {
    "selector": "button[type='submit']"
  }
}

🐛 一般的な問題のトラブルシューティング

🛠️ セキュリティ機能

安全なAI駆動の自動化のために構築されたエンタープライズグレードのセキュリティ。

• 🔒 サンドボックス実行：すべてのコードは、厳格なリソース制限を持つ分離された環境で実行されます。
• 🔍 入力検証：高度な静的解析により、危険なコードパターンを検出してブロックします。
• 📝 包括的な監査：暗号化されたログがすべての操作を完全に追跡可能にします。
• 🖼️ 安全なスクリーンショット：明確なユーザー通知を伴う暗号化されたスクリーンショットデータ。
• ⚠️ リスク評価：構成可能なセキュリティしきい値を持つ自動脅威検出。
• 🚫 ゼロトラスト：eval、ファイルシステムアクセス、およびネットワーク要求などの危険な機能は、デフォルトでブロックされます。

安全第一：すべてのコマンドは、アプリケーションに到達する前に、安全なサンドボックスで分析、検証、および実行されます。

🔧 利用可能なツール

launch_electron_app

デバッグ機能を備えたElectronアプリケーションを起動します。

{
  "appPath": "/path/to/electron-app",
  "devMode": true,  // ポート9222でChrome DevTools Protocolを有効にする
  "args": ["--enable-logging", "--dev"]
}

返り値：プロセスIDと起動確認

get_electron_window_info

Chrome DevTools Protocolを介して包括的なウィンドウとターゲット情報を取得します。

{
  "includeChildren": true  // 子ウィンドウとDevToolsインスタンスを含める
}

返り値：

• ウィンドウID、タイトル、URL、およびタイプ
• DevTools Protocolターゲット情報
• プラットフォーム詳細とプロセス情報

take_screenshot

PlaywrightとChrome DevTools Protocolを使用して高品質のスクリーンショットを撮ります。

{
  "outputPath": "/path/to/screenshot.png",  // オプション: デフォルトは一時ディレクトリ
  "windowTitle": "My App"  // オプション: 特定のウィンドウをターゲットにする
}

特徴：

• 非侵入的なキャプチャ（ウィンドウを前面に持ってこない）
• 任意のElectronアプリで動作する
• 必要に応じてプラットフォーム固有のツールにフォールバックする

send_command_to_electron

WebSocketを介して実行中のElectronアプリケーションでJavaScriptコマンドを実行します。

{
  "command": "eval",  // 組み込みコマンド: eval, get_title, get_url, click_button, console_log
  "args": {
    "code": "document.querySelector('button').click(); 'Button clicked!'"
  }
}

強化されたUIインタラクションコマンド：

• find_elements：すべてのインタラクティブUI要素をそのプロパティと位置とともに分析します。
• click_by_text：表示テキスト、aria-label、またはタイトルで要素をクリックします（セレクタよりも信頼性が高い）。
• fill_input：セレクタ、プレースホルダーテキスト、または関連するラベルテキストで入力フィールドを埋めます。
• select_option：値または表示テキストでドロップダウンオプションを選択します。
• get_page_structure：すべてのページ要素（ボタン、入力、セレクト、リンク）の整理された概要を取得します。
• get_title：ドキュメントのタイトルを取得します。
• get_url：現在のURLを取得します。
• get_body_text：表示されるテキストコンテンツを抽出します。
• click_button：CSSセレクタでボタンをクリックします（基本的な方法）。
• console_log：コンソールメッセージを送信します。
• eval：カスタムJavaScriptコードを実行します。

推奨ワークフロー：まずget_page_structureを使用して利用可能な要素を理解し、次にclick_by_textまたはfill_inputなどの特定のインタラクションコマンドを使用します。

read_electron_logs

メインプロセス、レンダラー、およびコンソールからアプリケーションログをストリームします。

{
  "logType": "all",  // オプション: "all", "main", "renderer", "console"
  "lines": 50,       // 最近の行数
  "follow": false    // ライブログをストリームする
}

close_electron_app

Electronアプリケーションを正常に閉じます。

{
  "force": false  // 応答しない場合は強制終了する
}

build_electron_app

配布用のElectronアプリケーションをビルドします。

{
  "projectPath": "/path/to/project",
  "platform": "darwin",  // win32, darwin, linux
  "arch": "x64",         // x64, arm64, ia32
  "debug": false
}

🔧 技術詳細

アーキテクチャ

Chrome DevTools Protocol統合

• 汎用互換性：リモートデバッグが有効になっている任意のElectronアプリで動作します。
• リアルタイム通信：レンダラープロセスとのWebSocketベースのコマンド実行。
• アプリ修正不要：ターゲットアプリケーションに変更を加える必要がありません。

プロセス管理

• クリーンな環境：ELECTRON_RUN_AS_NODEやその他の環境変数を処理します。
• リソース追跡：PID、メモリ使用量、およびアプリケーションのライフサイクルを監視します。
• 正常なシャットダウン：適切なクリーンアップとプロセス終了を行います。

クロスプラットフォームサポート

• macOS：Playwright CDPを使用し、screencaptureにフォールバックします。
• Windows：PowerShellベースのウィンドウ検出とキャプチャ。
• Linux：X11ウィンドウ管理（計画中）。

開発

前提条件

• Node.js 18+
• TypeScript 4.5+
• Electron - Electronアプリケーションの実行とテストに必要です。

# Electronをグローバルにインストールする（推奨）
npm install -g electron

# または、プロジェクト内にローカルにインストールする
npm install electron --save-dev

ターゲットアプリケーションの設定

MCPサーバーがあなたのElectronアプリケーションで動作するためには、リモートデバッグを有効にする必要があります。Electronアプリのメインプロセスにこのコードを追加します。

const { app } = require('electron');
const isDev = process.env.NODE_ENV === 'development' || process.argv.includes('--dev');

// 開発モードでリモートデバッグを有効にする
if (isDev) {
  app.commandLine.appendSwitch('remote-debugging-port', '9222');
}

代替アプローチ：

# デバッグを有効にしてアプリを起動する
electron . --remote-debugging-port=9222

# または、npmスクリプトを介して
npm run dev -- --remote-debugging-port=9222

注意：MCPサーバーは自動的にポート9222 - 9225をスキャンして、リモートデバッグが有効になっている実行中のElectronアプリケーションを検出します。

セットアップ

git clone https://github.com/halilural/electron-mcp-server.git
cd electron-mcp-server

npm install
npm run build

# テストを実行する
npm test

# 自動再ビルドを伴う開発モード
npm run dev

プロジェクト構造

src/
├── handlers.ts      # MCPツールハンドラー
├── index.ts         # サーバーエントリポイント
├── tools.ts         # ツール定義
├── screenshot.ts    # スクリーンショット機能
├── utils/
│   ├── process.ts   # プロセス管理とDevTools Protocol
│   ├── logs.ts      # ログ管理
│   └── project.ts   # プロジェクトスキャフォールディング
└── schemas/         # 検証用のJSONスキーマ

🔐 セキュリティとベストプラクティス

• サンドボックス実行：すべてのJavaScript実行は、ターゲットのElectronアプリ内に含まれます。
• パス検証：明示的に提供されたアプリケーションパスでのみ動作します。
• プロセス分離：起動された各アプリは独自のプロセス空間で実行されます。
• 永続的なアクセスなし：ターゲットアプリケーションに永続的な変更を加えません。

🤝 コントリビューション

コントリビューションを歓迎します！詳細については、Contributing Guideを参照してください。

1. リポジトリをフォークします。
2. 機能ブランチを作成します (git checkout -b feature/awesome-feature)。
3. 変更をコミットします (git commit -m 'Add awesome feature')。
4. ブランチにプッシュします (git push origin feature/awesome-feature)。
5. プルリクエストを開きます。

📄 ライセンス

MITライセンス - 詳細については、LICENSEファイルを参照してください。

☕ サポート

このプロジェクトが役に立った場合は、コーヒーを買ってくれることを検討してください！ ☕

あなたのサポートは、このプロジェクトを維持して改善するのに役立ちます。ありがとうございます！ 🙏

🙏 謝辞

• Model Context Protocol - 標準化されたAI - アプリケーションインターフェース
• Chrome DevTools Protocol - 汎用デバッグインターフェース
• Playwright - 信頼性の高いブラウザー自動化
• Electron - クロスプラットフォームデスクトップアプリケーション

🔗 リンク

• GitHubリポジトリ
• NPMパッケージ
• Model Context Protocol
• Chrome DevTools Protocolドキュメント

AI駆動の自動化でElectron開発を強化する準備はできましたか？ MCPサーバーをインストールして、今日からスマートなワークフローを構築しましょう！ 🚀