使用说明

电子MCP服务器

一个强大的模型上下文协议（MCP）服务器，提供全面的Electron应用程序自动化、调试和可观察性功能。通过Chrome DevTools Protocol集成，使用AI驱动的自动化来增强您的Electron开发工作流程。

⚠️ v2.0中的重大变化 --单身 send_command_to_electron 该工具已被拆分为约40个个体 electron_* 工具（例如。 electron_click_by_selector, electron_fill_input).这大大提高了LLM工具选择的准确性。 阅读 MIGRATION.md 完整版v1→ v2映射。 v1.x可通过以下方式获取 npm install @laststance/electron-mcp-server@^1.7.

演示

查看电子MCP服务器的运行情况：

🎬 在Vimeo上观看完整演示

观看使用AI驱动的MCP命令自动化Electron应用程序是多么容易。

🎯 是什么让它如此特别

通过以下方式改变您的电子开发体验 人工智能驱动的自动化:

🔄 实时UI自动化：单击按钮、填写表单并以编程方式与任何Electron应用程序交互
📸 可视化调试：在不中断开发的情况下截取屏幕截图并捕获应用程序状态
🔍 深层检测：实时提取DOM元素、应用程序数据和性能指标
⚡ DevTools协议集成：与任何Electron应用程序通用兼容-无需修改
🚀 发展可观察性：无缝监控日志、系统信息和应用程序行为

🔒 安全与配置

可配置的安全级别 在安全性和功能性之间取得平衡：

安全等级

🔒 严格：生产环境的最高安全性
⚖️ 平衡的：具有安全UI交互的默认安全性（推荐）
🔓 宽松的：为受信任的环境提供更多功能
🛠️ 发展：开发/测试的最低限制

环境配置

通过MCP客户端配置配置安全级别和其他设置：

VS代码MCP设置：

{
  "mcp": {
    "servers": {
      "electron": {
        "command": "npx",
        "args": ["-y", "@laststance/electron-mcp-server@latest"],
        "env": {
          "SECURITY_LEVEL": "balanced",
          "SCREENSHOT_ENCRYPTION_KEY":"your-32-byte-hex-string"
        }
      }
    }
  }
}

Claude桌面配置：

{
  "mcpServers": {
    "electron": {
      "command": "npx",
      "args": ["-y", "@laststance/electron-mcp-server@latest"],
      "env": {
        "SECURITY_LEVEL": "balanced",
        "SCREENSHOT_ENCRYPTION_KEY":"your-32-byte-hex-string"
      }
    }
  }
}

替代方案：本地.env文件（用于开发）：

# Create .env file in your project directory
SECURITY_LEVEL=balanced
SCREENSHOT_ENCRYPTION_KEY=your-32-byte-hex-string

安全级别行为：

级别	UI交互	DOM查询	属性访问	分配	函数调用	风险阈值
`strict`	❌ 已阻止	❌ 已阻止	✅ 允许	❌ 已阻止	❌ 不允许	低
`balanced`	✅ 允许	✅ 允许	✅ 允许	❌ 已阻止	✅ 安全UI功能	中等
`permissive`	✅ 允许	✅ 允许	✅ 允许	✅ 允许	✅ 扩展UI功能	高
`development`	✅ 允许	✅ 允许	✅ 允许	✅ 允许	✅ 所有功能	关键

环境设置：

复制 .env.example 到 .env
集 SECURITY_LEVEL 达到你想要的水平
根据需要配置其他安全设置

cp .env.example .env
# Edit .env and set SECURITY_LEVEL=balanced

安全UI交互命令

使用以下安全命令代替原始JavaScript eval：

// ✅ Secure button clicking
{
  "command": "click_by_text",
  "args": { "text": "Create New Encyclopedia" }
}

// ✅ Secure element selection
{
  "command": "click_by_selector",
  "args": { "selector": "button[title='Create']" }
}

// ✅ Secure keyboard shortcuts
{
  "command": "send_keyboard_shortcut",
  "args": { "text": "Ctrl+N" }
}

// ✅ Secure navigation
{
  "command": "navigate_to_hash",
  "args": { "text": "create" }
}

看 SECURITY_CONFIG.md 获取详细的安全文档。

🎯 正确的MCP使用指南

⚠️ 关键：论证结构

请注意，从这里开始使用v1文档。 以下部分（论点结构， send_command_to_electron 工具参考和长形式 v1示例）描述 v1 API.v2.0将单个工具拆分为 ~40人 electron_* 工具。如果你在v2，直接跳到 MIGRATION.md --v2工具接受他们的论点顶级，因此这里描述的结构陷阱不再适用。

最常见的错误 使用此MCP服务器时，参数结构不正确 send_command_to_electron 工具。

❌ 错误（导致“选择器为空”错误）：

{
  "command": "click_by_selector",
  "args": "button.submit-btn"  // ❌ Raw string - WRONG!
}

✅ 对的：

{
  "command": "click_by_selector",
  "args": {
    "selector": "button.submit-btn"  // ✅ Object with selector property
  }
}

📋 命令参数引用

命令	必需的参数	示例
`click_by_selector`	`{"selector": "css-selector"}`	`{"selector": "button.primary"}`
`click_by_text`	`{"text": "button text"}`	`{"text": "Submit"}`
`fill_input`	`{"value": "text", "selector": "..."}` 或 `{"value": "text", "placeholder": "..."}`	`{"placeholder": "Enter name", "value": "John"}`
`send_keyboard_shortcut`	`{"text": "key combination"}`	`{"text": "Ctrl+N"}`
`eval`	`{"code": "javascript"}`	`{"code": "document.title"}`
`get_title`, `get_url`, `get_body_text`	不需要参数	`{}` 或省略参数

🔄 推荐工作流程

检查：从以下内容开始 get_page_structure 或 debug_elements
目标：使用特定的选择器或基于文本的定位
互动：使用具有正确参数结构的适当命令
验证：截图或查看页面状态

// Step 1: Understand the page
{
  "command": "get_page_structure"
}

// Step 2: Click button using text (most reliable)
{
  "command": "click_by_text",
  "args": {
    "text": "Create New Encyclopedia"
  }
}

// Step 3: Fill form field
{
  "command": "fill_input",
  "args": {
    "placeholder": "Enter encyclopedia name",
    "value": "AI and Machine Learning"
  }
}

// Step 4: Submit with selector
{
  "command": "click_by_selector",
  "args": {
    "selector": "button[type='submit']"
  }
}

🐛 常见问题排查

错误	原因	解决方案
“提供的选择器为空”	传递字符串而不是对象	使用 `{"selector": "..."}`
“找不到元素”	选择器错误	使用 `get_page_structure` 首先
“命令被阻止”	安全限制	检查安全级别设置
“禁止点击-上次点击后太早”	同一目标在 `~1s` (`click_by_selector`) / `~2s` (`click_by_text`)--intentional React反双重提交去抖动	序列化调用(`await` 每个）或传递不同的选择器/文本
`Cmd+A` / `Cmd+C` / `Cmd+V` 什么都不做 `electron_press_key`	CDP绕过macOS操作系统级文本编辑快捷方式 `Input.dispatchKeyEvent` （仅限合成事件——与剧作家的约束相同）	使用 `electron_eval` 和 `el.select()` / `el.setSelectionRange(...)` / `navigator.clipboard.*`；用于应用程序级热键 `electron_send_keyboard_shortcut`

🛠️ 安全功能

企业级安全 为安全的人工智能自动化而构建：

🔒 沙盒执行：所有代码都在具有严格资源限制的隔离环境中运行
🔍 输入验证：高级静态分析检测并阻止危险的代码模式
📝 全面审计：加密日志以完全可追溯性跟踪所有操作
🖼️ 安全截图：加密的屏幕截图数据，带有清晰的用户通知
⚠️ 风险评估：具有可配置安全阈值的自动威胁检测
🚫 零信任：危险功能，如 eval默认情况下，文件系统访问和网络请求被阻止

安全第一：在到达应用程序之前，每个命令都会在安全的沙箱中进行分析、验证和执行。

�🚀 主要特点

🎮 应用控制与自动化

启动和管理：通过全生命周期控制启动、停止和监控Electron应用程序
交互式自动化：通过WebSocket在运行的应用程序中直接执行JavaScript代码
用户界面测试：自动化按钮点击、表单交互和用户工作流
进程管理：跟踪PID、监控资源使用情况并处理正常关机

📊 高级可观察性

电脑屏幕截图工具：使用Playwright和Chrome DevTools协议的非侵入式视觉快照
实时日志：带过滤的流式应用程序日志（主进程、渲染器、控制台）
窗口信息：获取详细的窗口元数据、标题、URL和目标信息
系统监控：跟踪内存使用情况、正常运行时间和性能指标

🛠️ 开发生产力

通用兼容性：适用于任何Electron应用程序，无需修改代码
DevTools集成：利用Chrome DevTools协议实现强大的调试功能
构建自动化：Windows、macOS和Linux的跨平台构建
环境管理：清洁环境处理和调试端口配置

📦 安装

VS代码集成（推荐）

添加到您的VS Code MCP设置中：

{
  "mcp": {
    "servers": {
      "electron": {
        "command": "npx",
        "args": ["-y", "@laststance/electron-mcp-server@latest"],
        "env": {
          "SECURITY_LEVEL": "balanced",
          "SCREENSHOT_ENCRYPTION_KEY": "your-32-byte-hex-string-here"
        }
      }
    }
  }
}

克劳德代码（CLI）

将此服务器添加到Claude Code的最快方法是 claude mcp add 命令。选项来了之前服务器名称；这 -- 分隔符标记spawn命令开始的位置。

项目范围（生活在 .mcp.json，通过git分享）：

claude mcp add electron-mcp \
  --env SECURITY_LEVEL=balanced \
  -- npx -y @laststance/electron-mcp-server@latest

用户范围（适用于此计算机上的每个项目）：

claude mcp add --scope user electron-mcp \
  --env SECURITY_LEVEL=balanced \
  -- npx -y @laststance/electron-mcp-server@latest

验证：

claude mcp list

💡 在Windows上，在spawn命令前加上前缀 cmd /c （例如。 -- cmd /c npx -y @laststance/electron-mcp-server@latest)因此，npx垫片正确地解决了这个问题。

游标IDE集成

Cursor IDE通过其配置文件支持MCP服务器。添加到光标MCP设置中：

位置:

macOS/Linux： ~/.cursor/mcp_config.json 或 ~/.config/cursor/mcp_config.json
窗户： %APPDATA%\Cursor\mcp_config.json

配置:

{
  "mcpServers": {
    "electron": {
      "command": "npx",
      "args": ["-y", "@laststance/electron-mcp-server@latest"],
      "env": {
        "SECURITY_LEVEL": "balanced",
        "SCREENSHOT_ENCRYPTION_KEY": "your-32-byte-hex-string-here"
      }
    }
  }
}

设置步骤:

打开光标IDE
首选设置 → 特性 → 模型上下文协议
启用MCP支持
将上述配置添加到MCP配置文件中
重新启动游标IDE

验证安装:

# Check if MCP server is accessible
curl http://localhost:9222/json

Claude桌面集成

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "electron": {
      "command": "npx",
      "args": ["-y", "@laststance/electron-mcp-server@latest"],
      "env": {
        "SECURITY_LEVEL": "balanced",
        "SCREENSHOT_ENCRYPTION_KEY": "your-32-byte-hex-string-here"
      }
    }
  }
}

OpenAI Codex命令行界面

Codex CLI通过以下方式注册MCP服务器 ~/.codex/config.toml （CLI和IDE扩展共享同一个文件）。

一个衬垫（首选）：

codex mcp add electron-mcp -- npx -y @laststance/electron-mcp-server@latest

或编辑 ~/.codex/config.toml 直接：

[mcp_servers.electron-mcp]
command = "npx"
args = ["-y", "@laststance/electron-mcp-server@latest"]

[mcp_servers.electron-mcp.env]
SECURITY_LEVEL = "balanced"

Codex在会话开始时自动启动服务器，并公开其 electron_* 内置工具旁边的工具。

全球安装

npm install -g @laststance/electron-mcp-server

🔧 可用工具

`launch_electron_app`

启动具有调试功能的Electron应用程序。

{
  "appPath": "/path/to/electron-app",
  "devMode": true,  // Enables Chrome DevTools Protocol on port 9222
  "args": ["--enable-logging", "--dev"]
}

退货：进程ID和启动确认

`get_electron_window_info`

通过Chrome DevTools协议获取全面的窗口和目标信息。

{
  "includeChildren": true  // Include child windows and DevTools instances
}

退货:

窗口ID、标题、URL和类型
DevTools协议目标信息
平台详细信息和流程信息

`take_screenshot`

使用Playwright和Chrome DevTools协议捕获高质量的屏幕截图。

{
  "outputPath": "/path/to/screenshot.png",  // Optional: defaults to temp directory
  "windowTitle": "My App"  // Optional: target specific window
}

特性:

非侵入式捕获（不将窗口带到前面）
适用于任何Electron应用程序
如果需要，可以回退到特定于平台的工具

`send_command_to_electron`

只有v1。 已在v2中删除。看 MIGRATION.md 为了按命令替换(electron_click_by_selector, electron_fill_input, electron_eval等等）。

通过WebSocket在正在运行的Electron应用程序中执行JavaScript命令。

{
  "command": "eval",  // Built-in commands: 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标签或标题单击元素（比选择器更可靠）
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",  // Options: "all", "main", "renderer", "console"
  "lines": 50,       // Number of recent lines
  "follow": false    // Stream live logs
}

`close_electron_app`

优雅地关闭Electron应用程序。

{
  "force": false  // Force kill if unresponsive
}

`build_electron_app`

构建电子应用程序以供分发。

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

🎮 演示应用程序

尝试交互式演示应用程序来测试MCP服务器的所有功能：

cd examples/demo-app
npm install
npm run dev

演示应用程序包括：

交互式UI元素：按钮、表单、下拉菜单、复选框
实时事件记录：监控所有交互
MCP命令示例：内置使用指南
DevTools集成：在端口9222上自动启用

看示例/演示应用程序/README.md 详细说明。

💡 用法示例

智能UI交互工作流程

// 1. First, understand the page structure
await send_command_to_electron({
  command: 'get_page_structure',
});

// 2. Click a button by its text (much more reliable than selectors)
await send_command_to_electron({
  command: 'click_by_text',
  args: {
    text: 'Login', // Finds buttons containing "Login" in text, aria-label, or title
  },
});

// 3. Fill inputs by their label or placeholder text
await send_command_to_electron({
  command: 'fill_input',
  args: {
    text: 'username', // Finds input with label "Username" or placeholder "Enter username"
    value: 'john.doe@example.com',
  },
});

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

// 4. Select dropdown options by visible text
await send_command_to_electron({
  command: 'select_option',
  args: {
    text: 'country', // Finds select with label containing "country"
    value: 'United States', // Selects option with this text
  },
});

// 5. Take a screenshot to verify the result
await take_screenshot();

高级元素检测

// Find all interactive elements with detailed information
await send_command_to_electron({
  command: 'find_elements',
});

// This returns detailed info about every clickable element and input:
// {
//   "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测试

// Launch app in development mode
await launch_electron_app({
  appPath: '/path/to/app',
  devMode: true,
});

// Take a screenshot
await take_screenshot();

// Click a button programmatically
await send_command_to_electron({
  command: 'eval',
  args: {
    code: "document.querySelector('#submit-btn').click()",
  },
});

// Verify the result
await send_command_to_electron({
  command: 'get_title',
});

开发调试

// Get window information
const windowInfo = await get_electron_window_info();

// Extract application data
await send_command_to_electron({
  command: 'eval',
  args: {
    code: 'JSON.stringify(window.appState, null, 2)',
  },
});

// Monitor logs
await read_electron_logs({
  logType: 'all',
  lines: 100,
});

性能监控

// Get system information
await send_command_to_electron({
  command: 'eval',
  args: {
    code: '({memory: performance.memory, timing: performance.timing})',
  },
});

// Take periodic screenshots for visual regression testing
await take_screenshot({
  outputPath: '/tests/screenshots/current.png',
});

🏗️ 建筑

Chrome DevTools协议集成

通用兼容性：适用于启用了远程调试的任何Electron应用程序
实时通信：使用渲染器进程执行基于WebSocket的命令
无应用程序修改：目标应用程序无需更改

进程管理

清洁环境：手柄 ELECTRON_RUN_AS_NODE 以及其他环境变量
资源跟踪：监控PID、内存使用和应用程序生命周期
优雅地关闭：适当的清理和流程终止

与跨平台支持

macOS：使用Playwright CDP和屏幕截图回退
视窗：基于PowerShell的窗口检测和捕获
Linux：X11窗口管理（计划中）

🧪 发展

先决条件

Node.js 18+
TypeScript 4.5+

电子 -运行和测试电子应用程序所需

# Install Electron globally (recommended)
npm install -g electron

# Or install locally in your project
npm install electron --save-dev

目标应用程序设置

为了使MCP服务器与您的Electron应用程序协同工作，您需要启用远程调试。将此代码添加到您的Electron应用程序的主进程中：

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

// Enable remote debugging in development mode
if (isDev) {
  app.commandLine.appendSwitch('remote-debugging-port', '9222');
}

替代方法：

# Launch your app with debugging enabled
electron . --remote-debugging-port=9222

# Or via npm script
npm run dev -- --remote-debugging-port=9222

注： MCP服务器自动扫描端口9222-9225，以检测启用远程调试的正在运行的Electron应用程序。

设置

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

npm install
npm run build

# Run tests
npm test

# Development mode with auto-rebuild
npm run dev

测试

该项目包括React兼容性的全面测试文件：

# Run React compatibility tests
cd tests/integration/react-compatibility
electron test-react-electron.js

看 tests/integration/react-compatibility/README.md 了解详细的测试说明和场景。

React兼容性

此MCP服务器已经过React应用程序的全面测试，可以正确处理常见的React模式：

✅ React事件处理：正确处理 preventDefault() 在点击处理程序中
✅ 表单输入检测：高级评分算法适用于React渲染的输入
✅ 组件交互：与React组件、钩子和状态管理兼容

项目结构

src/
├── handlers.ts      # MCP tool handlers
├── index.ts         # Server entry point
├── tools.ts         # Tool definitions
├── screenshot.ts    # Screenshot functionality
├── utils/
│   ├── process.ts   # Process management & DevTools Protocol
│   ├── logs.ts      # Log management
│   └── project.ts   # Project scaffolding
└── schemas/         # JSON schemas for validation

🔐 安全与最佳实践

沙盒执行：所有JavaScript执行都包含在目标Electron应用程序中
路径验证：仅在明确提供的应用程序路径上运行
进程隔离：每个启动的应用程序都在自己的进程空间中运行
无持久访问：不对目标应用程序进行永久性修改

🤝 贡献

我们欢迎捐款！请查看我们的贡献指南了解详情。

在报告问题之前：请使用标准 ISSUE_TEMPLATE.md 正确的错误报告格式。对于React兼容性问题或类似的技术问题，也请查看 REACT_COMPATIBILITY_ISSUES.md 详细的调试示例，包括正确的命令示例、错误输出和再现步骤。

分叉存储库
创建要素分支(git checkout -b feature/awesome-feature)
提交您的更改(git commit -m 'Add awesome feature')
推到分支(git push origin feature/awesome-feature)
打开拉取请求

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

🙌 署名与归属

原作者: 哈利尔·乌拉尔

这个项目是 halilural/electronic mcp服务器具有增强功能 游标IDE兼容性 并提高了稳定性。

分叉和维护者

@最后立场 -Cursor IDE集成改进、错误修复和持续维护

此分叉的关键改进

✅ 光标IDE兼容性：与Cursor IDE完全集成，实现无缝的人工智能电子自动化
✅ 增强的稳定性：改进了错误处理和可靠性
✅ 更好的文档：为本地开发和故障排除添加了全面的指南
✅ 作用域包：发表于 @laststance/electron-mcp-server 在npm上

为这个分叉做出贡献

我们欢迎捐款！如果您有改进或错误修复，请随时：

复刻此仓库
创建要素分支
提交一个包含您的改进的拉取请求

☕ 支持

如果这个项目对你有帮助，可以考虑给我买杯咖啡！ ☕

您的支持有助于我维护和改进这个项目。非常感谢。 🙏

🙏 致谢

模型上下文协议 -标准化AI应用界面
Chrome DevTools协议 -通用调试接口
剧作家 -可靠的浏览器自动化
电子 -跨平台桌面应用程序

🔗 链接

GitHub存储库
NPM包
原始存储库 -Halil Ural的原创项目
模型上下文协议
Chrome DevTools协议文档
光标IDE设置指南 -Cursor IDE集成的完整设置指南
问题模板 -标准化的错误报告格式
React兼容性问题文档 -React应用程序技术调试指南

准备好用AI驱动的自动化来加速您的Electron开发了吗？ 安装MCP服务器，立即开始构建更智能的工作流程！ 🚀