Electron MCP Server

🚀 Electron MCP 服務器

Electron MCP 服務器是一款強大的模型上下文協議（MCP）服務器，為 Electron 應用程序提供全面的自動化、調試和可觀測性功能。通過集成 Chrome DevTools 協議，藉助人工智能驅動的自動化，為你的 Electron 開發工作流程注入強大動力。

🚀 快速開始

安裝

VS Code 集成（推薦）

點擊下面的按鈕，在 VS Code 中使用 NPX 進行安裝：

在你的 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

啟動應用

要讓 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 應用程序。

✨ 主要特性

🎮 應用控制與自動化

• 啟動與管理：對 Electron 應用程序的整個生命週期進行啟動、停止和監控。
• 交互式自動化：通過 WebSocket 直接在運行的應用程序中執行 JavaScript 代碼。
• UI 測試：自動執行按鈕點擊、表單交互和用戶工作流。
• 進程管理：跟蹤進程 ID（PID）、監控資源使用情況並處理優雅關閉。

📊 高級可觀測性

• 截圖捕獲：使用 Playwright 和 Chrome DevTools 協議進行非侵入式視覺快照。
• 即時日誌：流式傳輸應用程序日誌（主進程、渲染器、控制檯）並支持過濾。
• 窗口信息：獲取詳細的窗口元數據、標題、URL 和目標信息。
• 系統監控：跟蹤內存使用情況、正常運行時間和性能指標。

🛠️ 開發效率提升

• 通用兼容性：無需修改代碼即可與任何 Electron 應用配合使用。
• DevTools 集成：利用 Chrome DevTools 協議實現強大的調試功能。
• 構建自動化：支持跨平臺構建，適用於 Windows、macOS 和 Linux。
• 環境管理：處理乾淨的環境並配置調試端口。

📦 安裝指南

VS Code 集成（推薦）

點擊下面的按鈕，在 VS Code 中使用 NPX 進行安裝：

在你的 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',
});

📚 詳細文檔

安全與配置

安全級別

• 🔒 嚴格模式：適用於生產環境的最高安全級別。
• ⚖️ 平衡模式：默認安全級別，具有安全的 UI 交互（推薦）。
• 🔓 寬鬆模式：適用於受信任環境的更多功能。
• 🛠️ 開發模式：開發/測試時的最小限制。

安全 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']"
  }
}

🐛 常見問題排查

🔧 技術細節

Chrome DevTools 協議集成

• 通用兼容性：可與任何啟用了遠程調試的 Electron 應用配合使用。
• 即時通信：基於 WebSocket 的命令執行與渲染進程進行通信。
• 無需應用修改：無需對目標應用程序進行任何更改。

進程管理

• 乾淨的環境：處理 ELECTRON_RUN_AS_NODE 和其他環境變量。
• 資源跟蹤：監控進程 ID、內存使用情況和應用程序生命週期。
• 優雅關閉：正確清理和終止進程。

跨平臺支持

• macOS：使用 Playwright CDP，在必要時使用 screencapture 作為後備。
• Windows：基於 PowerShell 的窗口檢測和捕獲。
• Linux：計劃支持 X11 窗口管理。

項目結構

src/
├── handlers.ts      # MCP 工具處理程序
├── index.ts         # 服務器入口點
├── tools.ts         # 工具定義
├── screenshot.ts    # 截圖功能
├── utils/
│   ├── process.ts   # 進程管理與 DevTools 協議
│   ├── logs.ts      # 日誌管理
│   └── project.ts   # 項目腳手架
└── schemas/         # 用於驗證的 JSON 模式

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🤝 貢獻

我們歡迎貢獻！請參閱我們的 貢獻指南 瞭解詳細信息。

1. 分叉倉庫。
2. 創建功能分支 (git checkout -b feature/awesome-feature)。
3. 提交更改 (git commit -m 'Add awesome feature')。
4. 推送到分支 (git push origin feature/awesome-feature)。
5. 打開拉取請求。

☕ 支持

如果這個項目對你有幫助，考慮請我喝杯咖啡！ ☕

你的支持有助於我維護和改進這個項目。感謝！ 🙏

🙏 致謝

• 模型上下文協議 - 標準化的人工智能應用接口。
• Chrome DevTools 協議 - 通用調試接口。
• Playwright - 可靠的瀏覽器自動化工具。
• Electron - 跨平臺桌面應用程序框架。

🔗 鏈接

• GitHub 倉庫
• NPM 包
• 模型上下文協議
• Chrome DevTools 協議文檔

準備好藉助人工智能驅動的自動化為你的 Electron 開發加速了嗎？ 安裝 MCP 服務器，立即開始構建更智能的工作流程！ 🚀