Electron Native MCP Server

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.

```bash
# 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.

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.