Electron MCP Server

@yawlabs/electron-mcp

点击一次，即可将其添加到本地 Yaw MCP 配置中，以便在每个 Yaw Terminal 会话中使用。也可以按下方说明手动安装。

**让 AI 助手真正擅长 Electron。**提供 18 种工具，解决 AI 模型经常产生幻觉的问题：上下文隔离、preload 桥接、fuses、CSP、代码签名、自动更新、各主版本之间的破坏性变更，以及 20 条官方安全建议。

这不是运行时调试器，而是一个开发智能层，让“给我写一些 Electron 代码”从时好时坏变成一次写对。

由 Yaw Labs 构建并维护。

为什么选择这个？

其他 Electron MCP 服务会给模型一个 shell，然后听天由命。这个不会。

• 安全无漏洞的 IPC — electron_scaffold_ipc_channel 一次调用即可生成主进程处理程序、类型化 preload 桥接、contextBridge 暴露接口以及渲染进程用法。不会使用 nodeIntegration: true，也不会将 ipcRenderer 直接挂到 window 上。
• 落实官方安全建议 — electron_audit_security 会根据 electronjs.org/docs/latest/tutorial/security 中 20 条建议的静态输入可验证项，对 BrowserWindow 配置、preload 脚本和 CSP 进行检查，共计 19 项。（第 20 项是会话权限处理，需要运行时上下文，因此会在报告页脚中标记。）这不是凭感觉判断。
• 感知版本的迁移 — electron_migrate_version 了解 v28 到 v41 之间的破坏性变更，并会准确说明升级版本时会有哪些内容失效。electron_check_deprecated_apis 会扫描代码，查找已移除的 API。
• 解释构建错误 — electron_diagnose_build_error 会解析 electron-builder/forge 输出并找出根本原因：Apple 代码签名、Windows 代码签名、原生模块重建、ASAR 打包、entitlements、路径引号问题。
• 现代化生产环境加固 — electron_configure_fuses 会生成 @electron/fuses 配置块，用于禁用未使用的运行时功能（Cookie 加密、Node CLI 标志、旧版加载行为）。electron_configure_csp 会生成能够与打包器和框架配合使用的 CSP，而不是阻止加载自身资源。
• 明确声明知识时效，而非默认其有效 — 每条响应都包含 _Knowledge last verified YYYY-MM-DD (Electron vN stable)_ 页脚。调用 electron_knowledge_version 可直接获取元数据。如果你的 Electron 版本高于页脚所示版本，工具会提醒你。
• 只读，无副作用 — 每个工具都会声明 readOnlyHint、destructiveHint: false、idempotentHint: true，因此 MCP 客户端可以跳过确认。工具绝不会接触你的文件系统、运行代码或调用 exec。
• 零运行时依赖 — 以单个打包文件的形式发布。无需耗时 5 分钟安装 node_modules，也无需将 electron 或 electron-builder 作为依赖项安装来增加项目体积。已发布软件包的 dependencies 为 {}；此仓库中 Dependabot 的警报针对的是 devDependencies。这些依赖的大部分（MCP SDK 的 HTTP 传输依赖：hono、express、ip-address、qs）不在打包文件中——此服务仅使用 stdio——但 SDK 默认 JSON Schema 验证器（ajv）所需的 fast-uri 已内联到 dist/index.js，因此针对它的安全公告会通过发布新版本解决，而不是重新安装依赖。

快速开始

无需 API 密钥。无需设置环境变量。只需安装即可。

1. 在项目根目录中创建 .mcp.json

macOS / Linux / WSL：

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

Windows：

{
  "mcpServers": {
    "electron": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/electron-mcp@latest"]
    }
  }
}

为什么 Windows 上还要多一步？ 从 Node 20 起，child_process.spawn 无法直接执行 .cmd 文件（Windows 上的 npx 就是这种文件）。使用 cmd /c 包装是标准的解决方法。

2. 重启并批准

重启 Claude Code（或你的 MCP 客户端），并在出现提示时批准 Electron MCP 服务。

就是这么简单。现在可以向你的 AI 助手提问：

“为我的 Electron 应用添加文件选择器”

“检查我的 BrowserWindow 配置是否存在安全问题”

“我的 electron-builder 因签名错误而失败了——这是输出内容”

“为我的 Vite + React 渲染器生成 CSP”

“如果我从 Electron 32 升级到 41，会有哪些问题？”

其他 MCP 客户端

客户端	配置文件
Claude Code	.mcp.json（项目根目录）或 ~/.claude.json（全局）
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code	.vscode/mcp.json

在以上任何客户端中，都使用上方所示的同一 JSON 代码块。

运行时和沙箱

如果已安装当前版本（0.18.0 或更高版本），启动器会优先使用 oam 运行时，否则会回退到运行它的 Node。无需配置；两者提供的服务相同。

选择启用沙箱。 使用 oam 时，服务可以在完全不授予权限的情况下通过 --permission 运行：无文件系统、无子进程、无网络、无环境变量。此服务不需要这些权限（每个工具都只根据其参数进行计算并返回 markdown），因此沙箱不会限制任何能力，还能将服务仅仅未使用的功能转为运行时拒绝。将 env 块添加到上文使用的任一配置块中（macOS / Linux / WSL 使用 npx，Windows 使用 cmd /c npx）：

"env": { "ELECTRON_MCP_SANDBOX": "1", "ELECTRON_MCP_RUNTIME": "oam" }

第二个变量会让沙箱变为必需：需要启动一个全新的 oam（0.18.0 或更高版本）来应用沙箱；设置 ELECTRON_MCP_RUNTIME=oam 后，如果 oam 缺失或不可用，启动就会报错，而不会运行未启用沙箱的服务。使用默认值 ELECTRON_MCP_RUNTIME=auto 时，启动器在这种情况下仍会提供服务，但不会使用 --permission，并会在 stderr 上输出一行说明及解决方法。想要在可用时启用沙箱，请使用 auto；想要确保启用沙箱，请使用 oam。

如何确认沙箱是否生效：每当服务被要求启用沙箱却在未启用的情况下运行时，都会在 stderr 上输出一行包含 electron-mcp: 和 runs WITHOUT --permission 的信息，以及解决方法（大多数 MCP 客户端会在日志中显示服务的 stderr）。应用沙箱时则不会输出此行。可通过 shell 确认：

ELECTRON_MCP_SANDBOX=1 ELECTRON_MCP_RUNTIME=oam npx -y @yawlabs/electron-mcp@latest --version

stdout 上显示版本号、退出码为 0，且没有 WITHOUT --permission 行，说明服务是在启用沙箱的 oam 下运行的；如果设置了 ELECTRON_MCP_RUNTIME=oam，oam 缺失时则会报错。

默认关闭沙箱是因为这会改变行为：未来版本如果确实需要某项能力，应在审查时失败，而不是在你的会话中失败。还有两点需要了解：

• 如果启动器本身已在 oam 下运行（Yaw MCP 会这样运行），沙箱会再启动一个 oam（如果没有安装更新版本，则使用宿主自己的二进制文件），因为只有全新启动的 oam 才能应用进程级标志。这会在启动时增加一次运行时引导，并对启动器找到的每个 oam 二进制文件执行一次 --version 探测。
• 通过变量请求启用沙箱，而不要在宿主命令上添加 --permission：在裸 --permission 下运行的启动器无法读取其环境，因此会忽略所有 ELECTRON_MCP_* 设置。宿主若同时授予 --allow-env（以及 --allow-child-process），则可以传递这些设置；此时，如果转交给 Node（ELECTRON_MCP_RUNTIME=node，或宿主 oam 版本低于最低要求），启动器会运行 node --permission，且不授予任何权限，因为 oam 0.18 会将宿主的 --permission / --allow-* 标志复制到 Node 的 NODE_OPTIONS 中，而 Node 会拒绝 --allow-env= 等仅适用于 oam 的标志（退出码为 9，不会提供服务）；启动器会输出一行 electron-mcp: 信息说明此情况。（直接运行、不使用启动器的形式为 oam --permission run <path>/dist/index.js。）

变量	效果
ELECTRON_MCP_RUNTIME=auto	使用最新的可用 oam，否则使用 Node（默认）
ELECTRON_MCP_RUNTIME=oam	使用最新的可用 oam，否则退出并报错
ELECTRON_MCP_RUNTIME=node	始终使用 Node（不会应用沙箱，且启动器会说明这一点）
ELECTRON_MCP_SANDBOX=1	在不授予任何权限的情况下，通过 --permission 运行 oam；true / yes / on 也会启用，0 / false / no / off 会禁用
OAM_BIN=/path/to/oam	如果此 oam 可用，则在发现其他 oam 之前使用它
OAM_INSTALL_DIR=/dir	oam 自身的安装目标变量；设置后，会在默认安装位置和 PATH 之前搜索 <dir>/oam

这两个变量的值都不区分大小写，且会去除首尾空格。启动器无法识别的值绝不会被静默忽略：它会被视为默认值（auto；关闭沙箱），并在 stderr 上指出，因此拼写错误不会悄悄将“必须启用沙箱”变成“方便时才启用沙箱”。

工具（18）

IPC 和进程架构（5）

• electron_scaffold_ipc_channel — 生成完整的 IPC 往返流程：主进程处理程序、preload 桥接、contextBridge 暴露、TypeScript 类型、渲染进程用法。
• electron_generate_preload_bridge — 生成包含多个 API 方法的安全 preload.ts，并使用 contextBridge。
• electron_audit_ipc_security — 分析 preload／主进程／渲染进程代码中的 IPC 安全问题（直接使用 ipcRenderer、缺少发送方验证、通道注入）。
• electron_generate_window_manager — 多窗口管理，包含生命周期跟踪和窗口间通信。
• electron_explain_process_model — 按版本说明 Electron 的多进程架构（主进程、渲染进程与实用程序进程，以及各自的职责）。

安全（4）

• electron_audit_security — 根据 20 项官方安全建议中的 19 项进行审计，这些建议可通过静态输入检测：BrowserWindow、preload、CSP、远程内容、沙箱。（第 20 项是会话权限处理，需要运行时上下文，并会在报告页脚中标出。）
• electron_configure_fuses — 生成用于生产环境加固的 @electron/fuses 配置（禁用 Cookie 加密回退、Node CLI 标志、旧版加载行为）。
• electron_configure_csp — 根据打包工具（Vite／webpack／Parcel）和框架（React／Vue／Svelte）生成相应的内容安全策略。
• electron_lint_security — 静态分析危险模式：shell.openExternal 接收不可信输入、@electron/remote、enableBlinkFeatures 等。

构建与分发（4）

• electron_diagnose_build_error — 解析 electron-builder／forge 错误并找出根本原因：代码签名、原生模块、ASAR、entitlements、路径引号。
• electron_configure_auto_update — 生成完整的 electron-updater 配置，包含事件及平台特定的签名注意事项。
• electron_configure_deep_linking — 在 Windows／macOS／Linux 上注册自定义协议。
• electron_scaffold_project — 生成安全、现代的 Electron 项目脚手架（contextIsolation: true、sandbox: true、preload、TypeScript、所选框架）。

迁移与兼容性（2）

• electron_migrate_version — 提供 Electron 版本间的迁移清单，涵盖破坏性变更、已弃用 API、平台支持变更。
• electron_check_deprecated_apis — 扫描源代码，检查在目标 Electron 版本中已弃用或已移除的 API。

性能（1）

• electron_audit_performance — 检测 7 种官方 Electron 性能反模式（主进程中的同步 I/O、急切加载大型模块等）。

参考（2）

• electron_explain_concept — 针对 8 个主题提供权威说明：进程模型、上下文隔离、沙箱、IPC、ASAR、fuses、代码签名、构建工具。
• electron_knowledge_version — 提供嵌入知识的元数据：最后验证日期、验证时的 Electron 稳定版、支持的版本范围。如果 Agent 不确定建议是否仍然适用，请调用此工具。

知识时效性

依赖嵌入式 Electron 知识的工具（破坏性变更、已弃用 API、安全建议、反模式、概念说明）会附加如下页脚：

_Knowledge last verified 2026-04-13 (Electron v41 stable). For anything newer, check https://releases.electronjs.org._

调用 electron_knowledge_version 可直接获取元数据。Electron 发布新的主版本时，KNOWLEDGE.md 会说明更新流程。

示例

以安全的方式添加文件选择器

> "Add a file picker that lets the renderer read the selected file's contents"
→ electron_scaffold_ipc_channel({
    direction: "renderer-to-main",
    channel: "open-file",
    returns: "string"
  })
  # Generates: main handler (dialog.showOpenDialog + fs.readFile),
  # preload bridge (contextBridge.exposeInMainWorld),
  # TypeScript types for window.api.openFile,
  # renderer usage example

审计现有应用的安全性

> "Check my Electron app for security issues — here's my main.ts and preload.ts"
→ electron_audit_security({ mainCode: "...", preloadCode: "..." })
  # Returns a graded report against 19 of 20 recommendations
  # (session permissions needs runtime context),
  # flagging nodeIntegration, missing contextIsolation,
  # unsandboxed renderers, loose CSP, and more.

诊断签名步骤失败的问题

> "electron-builder is exiting with: errSecInternalComponent — help"
→ electron_diagnose_build_error({ output: "..." })
  # Identifies macOS Keychain Access issue with code signing,
  # returns specific `security` CLI fix and CI reconfiguration.

规划 Electron 主版本升级

> "We're on Electron 32. What breaks if we jump to 41?"
→ electron_migrate_version({ from: 32, to: 41, sourceCode: "..." })
  # Returns breaking changes across each major (33, 34, 35, ...),
  # deprecated APIs found in your code,
  # platform support changes,
  # recommended test plan.

生成实际可用的 CSP

> "Generate a CSP for my Vite + React renderer that actually works"
→ electron_configure_csp({
    bundler: "vite",
    framework: "react",
    allowedOrigins: ["https://api.mycompany.com"]
  })
  # Returns a CSP that accounts for Vite's dev-mode WebSocket,
  # React's inline runtime, and blocks everything else.

故障排除

“工具输出被截断 / 过长”

• 有些脚手架工具会生成超过 10 KB 的代码。请让助手缩小范围后重新生成（单渠道而非多渠道桥接；生成单个框架脚手架而非进行比较）。

“针对我的 Electron 版本给出的建议有误”

• 检查 electron_knowledge_version。如果 Electron 在已验证日期之后发布了新的主版本，请对照其中链接的官方破坏性变更页面进行核实。
• 在仓库中提交问题，并注明具体工具、版本以及预期结果与实际结果。知识库更新会随次版本发布。

“Windows：MCP 服务无法启动”

• 使用快速入门部分中的 cmd /c npx ... 模式。Node 20+ 无法直接启动 .cmd 文件。

要求

• Node.js 20.11+
• 无运行时依赖

贡献

git clone https://github.com/YawLabs/electron-mcp.git
cd electron-mcp
npm install
npm run lint       # Biome check
npm run lint:fix   # Auto-fix
npm run build      # tsc + esbuild bundle
npm test           # node --test

完整工作流（包括发布流程）请参见 CONTRIBUTING.md。

许可证

MIT