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 服务器，立即开始构建更智能的工作流程！ 🚀