Electron Native MCP Server

A powerful Model Context Protocol (MCP) server for debugging and automating native Electron applications on macOS. This server provides comprehensive tools for DOM inspection, UI automation, and global hotkey triggering.

Features

🔍 DOM Inspection (7 tools)

Connect to Electron apps via Chrome DevTools Protocol (CDP)
List all debuggable targets (windows, webviews)
Query and inspect DOM elements
Execute JavaScript in Electron windows
Take screenshots of Electron content

🖱️ UI Automation (9 tools)

Control mouse (move, click, double-click, drag)
Keyboard input (type text, press keys)
Take screenshots of native UI
Get screen dimensions and mouse position
Full macOS accessibility API integration

⌨️ Global Hotkeys (4 tools)

Trigger custom keyboard shortcuts
Activate common macOS hotkeys (Spotlight, Mission Control, etc.)
Simulate application-specific shortcuts
Send complex key sequences

🔐 Permission Management (4 tools)

Check permission status
Request system permissions
Get setup instructions
Verify all required permissions

Requirements

macOS 12.0 or later
Node.js 18.0 or later
Electron app running with --inspect flag (for DOM inspection)

Required macOS Permissions

This server requires the following system permissions:

Accessibility - For UI automation and keyboard/mouse control
Screen Recording - For taking screenshots
Input Monitoring - For keyboard and mouse input

Installation

Quick Setup (Recommended)

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

This will:

Check system requirements
Install dependencies
Build the project
Provide configuration instructions
Optionally install the example app

Manual Setup

# Install dependencies
npm install

# Build the project
npm run build

Usage

Running the Server

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

# Production mode
npm start

Configuring with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Configuring with Other MCP Clients

The server uses stdio transport and can be integrated with any MCP-compatible client.

Tool Reference

DOM Inspection Tools

`list_electron_targets`

List all available Electron windows and webviews.

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

`connect_to_electron_target`

Connect to a specific Electron target for debugging.

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

`get_dom_tree`

Get the complete DOM tree of a connected target.

{
  "targetId": "target-id"
}

`query_selector`

Find a DOM element using CSS selector.

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

`execute_javascript`

Execute JavaScript in an Electron window.

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

UI Automation Tools

`click`

Click at coordinates or current position.

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

`type_text`

Type text at the current cursor position.

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

`press_key`

Press a key with optional modifiers.

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

`take_screenshot`

Capture a screenshot of the screen or region.

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

Hotkey Tools

`trigger_hotkey`

Trigger a custom keyboard shortcut.

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

`trigger_common_macos_hotkey`

Trigger a common macOS system hotkey.

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

Permission Tools

`check_all_permissions`

Check the status of all required permissions.

{}  // No parameters

Debugging Electron Apps

To debug an Electron app with this server:

Launch your Electron app with the inspect flag:

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

List available targets: Use the list_electron_targets tool to see all debuggable windows.
Connect to a target: Use connect_to_electron_target with the target ID.
Inspect and interact: Use DOM tools to query elements, execute JavaScript, etc.

Examples

Example 1: Click a Button in Electron App

// 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()" 
})

Example 2: Automate Native 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" })

Example 3: Trigger Spotlight

trigger_common_macos_hotkey({ hotkey: "spotlight" })

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Lint
npm run lint

# Format code
npm run format

Architecture

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

Troubleshooting

Permission Denied Errors

If you get permission errors, use the permission tools to check status:

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

Then grant the required permissions in System Settings.

Cannot Connect to Electron App

Make sure your Electron app is running with the --inspect flag:

your-app --inspect=9222

Screenshots Not Working

Ensure Screen Recording permission is granted for your terminal app (Terminal, iTerm2, VS Code, etc.).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Credits

Built with:

@modelcontextprotocol/sdk - MCP TypeScript SDK
chrome-remote-interface - Chrome DevTools Protocol client
@nut-tree/nut-js - Desktop automation
node-mac-permissions - macOS permissions