Electron Native MCP Server enables debugging, DOM inspection, and native UI automation for Electron apps on macOS through a local MCP endpoint. It exposes a set of tools to connect to Electron targets, inspect and manipulate the DOM, automate UI actions, trigger macOS hotkeys, and manage necessary permissions from a single, scriptable interface.

How to use

You run a local MCP server and connect to it from an MCP client. Start by launching your Electron app with the inspect flag so you can expose debugging targets. Then use the available tools to list targets, connect to a target, inspect and manipulate the DOM, automate UI actions, and trigger system hotkeys. You can also manage required permissions from the same interface to ensure your automation runs smoothly.

How to install

Prerequisites you need before installation include macOS 12.0 or later and Node.js 18.0 or later. Ensure your Electron app is prepared for debugging with the inspect flag.

# Quick setup (recommended)
./scripts/setup.sh

This script checks system requirements, installs dependencies, builds the project, and provides configuration instructions. It may also offer to install an example app.

# Manual setup
npm install
npm run build

Additional setup notes

To run the server in development, use auto-reload during development. For production, start the server with the production command. If you need to configure the server with a client, you can place the MCP configuration in your client setup and point it to the local stdio server.

Configuration with Claude Desktop

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

Running the server

Run in development mode for automatic reloads, or run in production mode for a stable build. Use the following commands to start the server in each mode.

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

# Production mode
npm start

Debugging Electron Apps with the server

To debug an Electron app, first launch the app with the inspect flag, then connect to the debuggable targets and begin DOM inspection or UI automation.

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

Then list targets, connect to one, and use the DOM and UI automation tools to interact with the app.

## Examples

Example workflows show how to list targets, connect to a target, query the DOM, and perform actions like clicking or typing.

## Development

Common development commands when working on the server project.

Install dependencies

npm install

Run in development mode

npm run dev

Build the project

npm run build

Lint and format (optional)

npm run lint npm run format

## Architecture overview

The server integrates the Chrome DevTools Protocol for DOM inspection, macOS accessibility APIs for UI automation, and a set of tools organized into DOM inspection, UI automation, hotkeys, and permission management.

## Troubleshooting

If you encounter permission or connection issues, ensure the required macOS permissions are granted and that the Electron app is started with the correct debugging flags.

## Notes and examples

The server provides tools for DOM inspection, UI automation, global hotkeys, and permission management. Use the tools to list targets, connect to a target, inspect the DOM, execute JavaScript, click, type text, press keys, take screenshots, trigger hotkeys, and check or request permissions as needed.

## Available tools

### list\_electron\_targets

List all available Electron windows and webviews.

### connect\_to\_electron\_target

Connect to a specific Electron target for debugging.

### get\_dom\_tree

Get the complete DOM tree of a connected target.

### query\_selector

Find a DOM element using a CSS selector.

### execute\_javascript

Execute JavaScript in an Electron window.

### click

Click at coordinates or current position.

### type\_text

Type text at the current cursor position.

### press\_key

Press a key with optional modifiers.

### take\_screenshot

Capture a screenshot of the screen or region.

### trigger\_hotkey

Trigger a custom keyboard shortcut.

### trigger\_common\_macos\_hotkey

Trigger a common macOS system hotkey.

### check\_all\_permissions

Check the status of all required permissions.

### get\_permission\_instructions

Get setup instructions for a specific permission.

### request\_permissions

Request system permissions.

### verify\_all\_permissions

Verify that all required permissions have been granted.