Debug Electron MCP

调试电子MCP

用于自动化、调试和测试Electron应用程序的最终模型上下文协议（MCP）服务器。

利用人工智能的力量与任何电子应用程序进行交互。通过与Claude Code、Claude Desktop、Cursor和其他MCP客户端兼容的标准化协议，检查DOM、按文本单击按钮、填写表单、捕获屏幕截图和读取控制台日志。

全局安装一次——它会自动检测您所在的项目并确定其范围。在多个会话中使用多个Electron应用程序，无需额外配置。

______________________________________________________________________

目录

• 特性
• 快速开始
• 多项目如何运作
• 启用远程调试（必需）
• 使用指南

- 核心工作流程 - 工具参考 - 项目管理工具 - 交互命令

• 高级：HTTP服务器模式
• 发展
• 故障排除
• 许可证

______________________________________________________________________

特性

通用兼容性

• 适用于任何Electron应用程序：不需要修改源代码。
• 零设置集成：完全通过Chrome DevTools协议（CDP）连接。
• 跨平台：支持Windows、macOS和Linux。

自动检测和多项目

• 自动项目检测：阅读您的 package.json name或文件夹名——每个项目都会自动获得自己的端口。
• 每个项目没有配置：全局安装MCP一次。在任何Electron项目中打开Claude Code，它都能正常工作。
• 多个应用程序，无冲突：端口9222上的应用A，端口9223上的应用B——每个Claude Code会话只与自己的应用对话。
• 磁盘上的共享注册表: ~/.debug-electron-mcp.json 跨会话持久化端口分配并重新启动。

智能UI自动化

• 语义交互：具体 click_by_text 和 fill_input 命令“只是工作”
• 视觉智能：截取特定窗口的屏幕截图以验证状态。
• 强有力的行动：高级 drag, hover, type，以及 wait 用于复杂工作流的命令。

深度可观察性

• DOM检查: get_page_structure 为AI提供交互式作战地图的干净副本。
• 日志流：实时读取主进程、渲染器和控制台日志。
• 演出：监控内存、时间和系统指标。

______________________________________________________________________

快速开始

步骤1：添加到MCP配置中（一次）

克劳德代码（全球——推荐）

添加 ~/.claude/settings.json:

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

完成。现在，每个Claude Code会话都有可用的Electron工具。

VS代码/光标

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

克劳德桌面版

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

步骤2：通过远程调试启动您的Electron应用程序

首次在项目中使用MCP时，它会自动注册项目并分配端口。检查 list_projects() 要查看分配的端口，请启动应用程序：

electron . --remote-debugging-port=9222

就是这样。MCP会自动检测您的项目，并将所有命令范围限定在该项目上。

______________________________________________________________________

多项目如何运作

MCP会自动检测它在哪个项目中运行——没有标志，没有 projectName 在每次调用中，没有针对每个项目的配置。

当Claude Code在您的项目中打开时会发生什么：

1. Claude Code从您的项目目录中生成MCP服务器
2. MCP读取您的 package.json name（或使用文件夹名称）
3. 如果项目已注册，则使用现有端口
4. 如果它是新的，它会自动注册并分配下一个空闲端口
5. 所有工具调用都会自动作用于该项目的端口

示例：两个应用程序，两个会话

# Session A: Claude Code in ~/projects/music-app/
# MCP auto-detects "music-app" → port 9222
take_screenshot()  # only sees music-app

# Session B: Claude Code in ~/projects/todo-app/
# MCP auto-detects "todo-app" → port 9223
take_screenshot()  # only sees todo-app

没有相声。无需手动设置。每个会话都知道自己的应用程序。

检查您分配的端口

使用 list_projects() 从任何会话中查看所有注册项目及其端口：

list_projects()
# -> Registered projects (2):
#    - music-app: port 9222 [connected (1 window(s))]
#    - todo-app: port 9223 [not connected]

注册表持久性

端口分配保存到 ~/.debug-electron-mcp.json 并在所有会话中共享：

{
  "portRange": [9222, 9322],
  "projects": {
    "music-app": { "port": 9222 },
    "todo-app": { "port": 9223 }
  }
}

人工项目管理

您还可以使用内置工具显式管理项目：

register_project({ projectName: "my-app" })                    # register with auto-assigned port
register_project({ projectName: "my-app", port: 9250 })        # register with specific port
unregister_project({ projectName: "old-app" })                  # free a port
list_projects()                                                  # see all projects

用projectName覆盖

如果您需要针对与当前会话不同的项目，请传递 projectName 明确地：

take_screenshot({ projectName: "other-app" })

______________________________________________________________________

启用远程调试（必需）

您的Electron应用程序 必须在启用远程调试的情况下运行 在分配给您项目的港口。

使用 list_projects() 要检查分配的端口，请使用该端口启动应用程序。

方法1：命令行标记（最简单）

electron . --remote-debugging-port=9222

方法2:package.json（持久化）

"scripts": {
  "start": "electron .",
  "dev:debug": "electron . --remote-debugging-port=9222"
}

然后运行 npm run dev:debug.

方法3：程序化（最适合代码库）

const { app } = require('electron');

if (process.env.NODE_ENV === 'development' || process.argv.includes('--dev')) {
  const port = process.env.DEBUG_PORT || '9222';
  app.commandLine.appendSwitch('remote-debugging-port', port);
  console.log(`Remote debugging enabled on port ${port}`);
}

验证

打开 http://localhost: /json 在您的浏览器中。如果你看到一个JSON目标列表，那么你就准备好了。

______________________________________________________________________

使用指南

核心工作流程

1. 检查：使用 get_page_structure 查看可用的按钮和输入。
2. 目标：确定您想要的元素（例如，带有文本“登录”的按钮）。
3. 法案：发送如下命令 click_by_text 或 fill_input.
4. 验证：使用 take_screenshot 或 get_title 确认操作成功。

工具参考

项目管理工具

交互命令

在里面使用这些 send_command_to_electron:

点击和选择

输入和表单

观察

高级

______________________________________________________________________

高级：HTTP服务器模式

对于需要多个AI客户端共享的单个长期服务器的高级用例，可以在HTTP模式下运行服务器。

注： 大多数用户不需要这个。标准设置会自动检测项目，并处理多个应用程序，无需额外配置。

第一步： 启动服务器：

npx @debugelectron/debug-electron-mcp@latest serve
npx @debugelectron/debug-electron-mcp@latest serve --port 4000

第二步： 将您的MCP配置指向以下URL：

{
  "mcpServers": {
    "debug-electron-mcp": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

步骤3： 通过 projectName 在工具调用中（HTTP模式下没有自动检测）：

send_command_to_electron({ projectName: "music-app", command: "get_title" })

健康检查： http://localhost:3100/health

______________________________________________________________________

发展

先决条件

• Node.js 18+
• npm或pnpm

设置

git clone https://github.com/TheDarkSkyXD/debug-electron-mcp.git
cd debug-electron-mcp
npm install
npm run build

本地运行

npm run dev                               # stdio mode
npx tsx src/index.ts --project my-app     # explicit project scope
npx tsx src/index.ts serve                # HTTP mode

测试

npm test                  # unit tests
npm run test:react        # integration tests

______________________________________________________________________

故障排除

“找不到目标”/“没有运行的Electron应用程序”

• 检查您分配的端口 list_projects().
• 使用以下命令启动您的Electron应用程序 `--remote-debugging-port=

`.

• 验证：打开 `http://localhost:

/json` 在您的浏览器中。

“项目'xyz'未注册”

• 自动检测不应该发生这种情况。如果是，跑 register_project({ projectName: "xyz" }).
• 检查 list_projects() 查看已注册的项目。

检测到错误的项目

• MCP使用您的 package.json name，或者如果不存在package.json，则使用文件夹名称。
• 要覆盖，请使用 --project 标志： "args": ["-y", "@debugelectron/debug-electron-mcp@latest", "--project", "correct-name"]

“没有可用的自由端口”

• 默认范围为9222-9322（100个端口）。
• 未使用的空闲端口： unregister_project({ projectName: "old-app" }).

“选择器为空”错误

• 错误： {"command": "click_by_selector", "args": ".btn"}
• 对的： {"command": "click_by_selector", "args": {"selector": ".btn"}}

______________________________________________________________________

许可证

MIT许可证。看 许可证 了解详情。

积分