Electron Native MCP Server

Electron原生MCP服务器

一个强大的模型上下文协议（MCP）服务器，用于在macOS上调试和自动化本机Electron应用程序。该服务器为DOM检查、UI自动化和全局热键触发提供了全面的工具。

特性

🔍 DOM检查（7个工具）

• 通过Chrome DevTools协议（CDP）连接到Electron应用程序
• 列出所有可调试的目标（窗口、Web视图）
• 查询和检查DOM元素
• 在Electron窗口中执行JavaScript
• 拍摄电子内容的截图

🖱️ UI自动化（9个工具）

• 控制鼠标（移动、单击、双击、拖动）
• 键盘输入（键入文本、按键）
• 截屏原生UI
• 获取屏幕尺寸和鼠标位置
• 完整的macOS可访问性API集成

⌨️ 全局热键（4个工具）

• 触发自定义键盘快捷键
• 激活常见的macOS热键（聚光灯、任务控制等）
• 模拟特定于应用程序的快捷方式
• 发送复杂的按键序列

🔐 权限管理（4个工具）

• 检查权限状态
• 请求系统权限
• 获取设置说明
• 验证所有必需的权限

需求

• macOS 12.0或更高版本
• Node.js 18.0或更晚
• 电子应用程序 跑步与 --inspect 标志（用于DOM检查）

所需的macOS权限

此服务器需要以下系统权限：

1. 无障碍 -用于UI自动化和键盘/鼠标控制
2. 屏幕录制 -用于截图
3. 输入监控 -用于键盘和鼠标输入

安装

快速设置（推荐）

# Run the setup script
./scripts/setup.sh

这将：

• 检查系统要求
• 安装依赖项
• 构建项目
• 提供配置说明
• 可选择安装示例应用程序

手动设置

# Install dependencies
npm install

# Build the project
npm run build

用法

运行服务器

# Development mode (with auto-reload)
npm run dev

# Production mode
npm start

使用Claude Desktop进行配置

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "electron-native": {
      "command": "node",
      "args": ["/path/to/electron-native-mcp/dist/index.js"]
    }
  }
}

配置其他MCP客户端

服务器使用stdio传输，可以与任何兼容MCP的客户端集成。

工具参考

DOM检查工具

list_electron_targets

列出所有可用的Electron窗口和网络视图。

// Example usage
{
  "host": "localhost",  // optional
  "port": 9222          // optional
}

connect_to_electron_target

连接到特定的Electron目标进行调试。

{
  "targetId": "target-id-from-list"
}

get_dom_tree

获取连接目标的完整DOM树。

{
  "targetId": "target-id"
}

query_selector

使用CSS选择器查找DOM元素。

{
  "targetId": "target-id",
  "selector": "#myButton"
}

execute_javascript

在Electron窗口中执行JavaScript。

{
  "targetId": "target-id",
  "code": "document.title"
}

UI自动化工具

click

单击坐标或当前位置。

{
  "x": 100,           // optional
  "y": 200,           // optional
  "button": "left"    // left, right, or middle
}

type_text

在当前光标位置键入文本。

{
  "text": "Hello, World!"
}

press_key

按带有可选修饰符的键。

{
  "key": "enter",
  "modifiers": ["command", "shift"]  // optional
}

take_screenshot

捕获屏幕或区域的屏幕截图。

{
  "x": 0,        // optional
  "y": 0,        // optional
  "width": 800,  // optional
  "height": 600  // optional
}

热键工具

trigger_hotkey

触发自定义键盘快捷键。

{
  "key": "space",
  "modifiers": ["command"]
}

trigger_common_macos_hotkey

触发常见的macOS系统热键。

{
  "hotkey": "spotlight"  // spotlight, mission_control, app_switcher, etc.
}

权限工具

check_all_permissions

检查所有必需权限的状态。

{}  // No parameters

调试电子应用程序

要使用此服务器调试Electron应用程序，请执行以下操作：

1. 使用inspect标志启动您的Electron应用程序：

   /path/to/your/app.app/Contents/MacOS/YourApp --inspect=9222

1. 列出可用目标：

使用 list_electron_targets 查看所有可调试窗口的工具。

1. 连接到目标：

使用 connect_to_electron_target 使用目标ID。

1. 检查并互动：

使用DOM工具查询元素、执行JavaScript等。

例子

示例1：点击Electron应用程序中的按钮

// 1. List targets
list_electron_targets()

// 2. Connect to target
connect_to_electron_target({ targetId: "..." })

// 3. Find button
query_selector({ targetId: "...", selector: "#submitButton" })

// 4. Click it via JavaScript
execute_javascript({ 
  targetId: "...", 
  code: "document.querySelector('#submitButton').click()" 
})

示例2：自动化原生UI

// 1. Check permissions
check_all_permissions()

// 2. Move mouse and click
click({ x: 500, y: 300 })

// 3. Type text
type_text({ text: "Hello!" })

// 4. Press Enter
press_key({ key: "enter" })

示例3：触发聚光灯

trigger_common_macos_hotkey({ hotkey: "spotlight" })

发展

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Lint
npm run lint

# Format code
npm run format

建筑

electron-native-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server setup
│   ├── types/                # TypeScript types
│   ├── lib/                  # Core libraries
│   │   ├── cdp-client.ts     # Chrome DevTools Protocol client
│   │   ├── accessibility.ts  # macOS accessibility wrapper
│   │   └── permissions.ts    # Permission manager
│   └── tools/                # MCP tools
│       ├── dom/              # DOM inspection tools
│       ├── ui/               # UI automation tools
│       ├── hotkey/           # Hotkey tools
│       └── permissions/      # Permission tools
├── package.json
├── tsconfig.json
└── README.md

故障排除

权限被拒绝错误

如果您遇到权限错误，请使用权限工具检查状态：

check_all_permissions()
get_permission_instructions({ permission: "accessibility" })

然后在系统设置中授予所需的权限。

无法连接到Electron应用程序

确保您的Electron应用程序正在运行 --inspect 标志：

your-app --inspect=9222

截图不起作用

确保为您的终端应用程序（终端、iTerm2、VS代码等）授予了屏幕录制权限。

贡献

欢迎投稿！请随时提交拉取请求。

许可证

麻省理工学院

鸣谢

内置：

• @模型上下文协议/sdk -MCP TypeScript SDK
• chrome远程接口 -Chrome DevTools协议客户端
• @坚果树/坚果js -桌面自动化
• 节点mac权限 -macOS权限