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:

1. Accessibility - For UI automation and keyboard/mouse control
2. Screen Recording - For taking screenshots
3. 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:

1. Launch your Electron app with the inspect flag:

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

2. List available targets:
   Use the list_electron_targets tool to see all debuggable windows.

3. Connect to a target:
   Use connect_to_electron_target with the target ID.

4. 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