Electron MCP Server

GitHub license npm version MCP

A powerful Model Context Protocol (MCP) server that provides comprehensive Electron application automation, debugging, and observability capabilities. Supercharge your Electron development workflow with AI-powered automation through Chrome DevTools Protocol integration.

Demo

See the Electron MCP Server in action:

Watch Demo Video

🎬 Watch Full Demo on Vimeo

Watch how easy it is to automate Electron applications with AI-powered MCP commands.

🎯 What Makes This Special

Transform your Electron development experience with AI-powered automation:

🔄 Real-time UI Automation: Click buttons, fill forms, and interact with any Electron app programmatically
📸 Visual Debugging: Take screenshots and capture application state without interrupting development
🔍 Deep Inspection: Extract DOM elements, application data, and performance metrics in real-time
⚡ DevTools Protocol Integration: Universal compatibility with any Electron app - no modifications required
🚀 Development Observability: Monitor logs, system info, and application behavior seamlessly

🔒 Security & Configuration

Configurable security levels to balance safety with functionality:

Security Levels

🔒 STRICT: Maximum security for production environments
⚖️ BALANCED: Default security with safe UI interactions (recommended)
🔓 PERMISSIVE: More functionality for trusted environments
🛠️ DEVELOPMENT: Minimal restrictions for development/testing

Environment Configuration

Configure the security level and other settings through your MCP client configuration:

VS Code MCP Settings:

{ "mcp": { "servers": { "electron": { "command": "npx", "args": ["-y", "electron-mcp-server"], "env": { "SECURITY_LEVEL": "balanced", "SCREENSHOT_ENCRYPTION_KEY":"your-32-byte-hex-string" } } } } }

Claude Desktop Configuration:

{ "mcpServers": { "electron": { "command": "npx", "args": ["-y", "electron-mcp-server"], "env": { "SECURITY_LEVEL": "balanced", "SCREENSHOT_ENCRYPTION_KEY":"your-32-byte-hex-string" } } } }

Alternative: Local .env file (for development):

# Create .env file in your project directory SECURITY_LEVEL=balanced SCREENSHOT_ENCRYPTION_KEY=your-32-byte-hex-string

Security Level Behaviors:

Level	UI Interactions	DOM Queries	Property Access	Assignments	Function Calls	Risk Threshold
`strict`	❌ Blocked	❌ Blocked	✅ Allowed	❌ Blocked	❌ None allowed	Low
`balanced`	✅ Allowed	✅ Allowed	✅ Allowed	❌ Blocked	✅ Safe UI functions	Medium
`permissive`	✅ Allowed	✅ Allowed	✅ Allowed	✅ Allowed	✅ Extended UI functions	High
`development`	✅ Allowed	✅ Allowed	✅ Allowed	✅ Allowed	✅ All functions	Critical

Environment Setup:

Copy .env.example to .env
Set SECURITY_LEVEL to your desired level
Configure other security settings as needed

cp .env.example .env # Edit .env and set SECURITY_LEVEL=balanced

Secure UI Interaction Commands

Instead of raw JavaScript eval, use these secure commands:

// ✅ Secure button clicking { "command": "click_by_text", "args": { "text": "Create New Encyclopedia" } } // ✅ Secure element selection { "command": "click_by_selector", "args": { "selector": "button[title='Create']" } } // ✅ Secure keyboard shortcuts { "command": "send_keyboard_shortcut", "args": { "text": "Ctrl+N" } } // ✅ Secure navigation { "command": "navigate_to_hash", "args": { "text": "create" } }

See SECURITY_CONFIG.md for detailed security documentation.

🎯 Proper MCP Usage Guide

⚠️ Critical: Argument Structure

The most common mistake when using this MCP server is incorrect argument structure for the send_command_to_electron tool.

❌ Wrong (causes "selector is empty" errors):

{ "command": "click_by_selector", "args": "button.submit-btn" // ❌ Raw string - WRONG! }

✅ Correct:

{ "command": "click_by_selector", "args": { "selector": "button.submit-btn" // ✅ Object with selector property } }

📋 Command Argument Reference

Command	Required Args	Example
`click_by_selector`	`{"selector": "css-selector"}`	`{"selector": "button.primary"}`
`click_by_text`	`{"text": "button text"}`	`{"text": "Submit"}`
`fill_input`	`{"value": "text", "selector": "..."}` or `{"value": "text", "placeholder": "..."}`	`{"placeholder": "Enter name", "value": "John"}`
`send_keyboard_shortcut`	`{"text": "key combination"}`	`{"text": "Ctrl+N"}`
`eval`	`{"code": "javascript"}`	`{"code": "document.title"}`
`get_title` , `get_url` , `get_body_text`	No args needed	`{}` or omit args

🔄 Recommended Workflow

Inspect: Start with get_page_structure or debug_elements
Target: Use specific selectors or text-based targeting
Interact: Use the appropriate command with correct argument structure
Verify: Take screenshots or check page state

// Step 1: Understand the page { "command": "get_page_structure" } // Step 2: Click button using text (most reliable) { "command": "click_by_text", "args": { "text": "Create New Encyclopedia" } } // Step 3: Fill form field { "command": "fill_input", "args": { "placeholder": "Enter encyclopedia name", "value": "AI and Machine Learning" } } // Step 4: Submit with selector { "command": "click_by_selector", "args": { "selector": "button[type='submit']" } }

🐛 Troubleshooting Common Issues

Error	Cause	Solution
"The provided selector is empty"	Passing string instead of object	Use `{"selector": "..."}`
"Element not found"	Wrong selector	Use `get_page_structure` first
"Command blocked"	Security restriction	Check security level settings
"Click prevented - too soon"	Rapid consecutive clicks	Wait before retrying

🛠️ Security Features

Enterprise-grade security built for safe AI-powered automation:

🔒 Sandboxed Execution: All code runs in isolated environments with strict resource limits
🔍 Input Validation: Advanced static analysis detects and blocks dangerous code patterns
📝 Comprehensive Auditing: Encrypted logs track all operations with full traceability
🖼️ Secure Screenshots: Encrypted screenshot data with clear user notifications
⚠️ Risk Assessment: Automatic threat detection with configurable security thresholds
🚫 Zero Trust: Dangerous functions like eval, file system access, and network requests are blocked by default

Safety First: Every command is analyzed, validated, and executed in a secure sandbox before reaching your application.

�🚀 Key Features

🎮 Application Control & Automation

Launch & Manage: Start, stop, and monitor Electron applications with full lifecycle control
Interactive Automation: Execute JavaScript code directly in running applications via WebSocket
UI Testing: Automate button clicks, form interactions, and user workflows
Process Management: Track PIDs, monitor resource usage, and handle graceful shutdowns

📊 Advanced Observability

Screenshot Capture: Non-intrusive visual snapshots using Playwright and Chrome DevTools Protocol
Real-time Logs: Stream application logs (main process, renderer, console) with filtering
Window Information: Get detailed window metadata, titles, URLs, and target information
System Monitoring: Track memory usage, uptime, and performance metrics

🛠️ Development Productivity

Universal Compatibility: Works with any Electron app without requiring code modifications
DevTools Integration: Leverage Chrome DevTools Protocol for powerful debugging capabilities
Build Automation: Cross-platform building for Windows, macOS, and Linux
Environment Management: Clean environment handling and debugging port configuration

📦 Installation

VS Code Integration (Recommended)

Install with NPX in VS Code

Add to your VS Code MCP settings:

{ "mcp": { "servers": { "electron": { "command": "npx", "args": ["-y", "electron-mcp-server"], "env": { "SECURITY_LEVEL": "balanced", "SCREENSHOT_ENCRYPTION_KEY": "your-32-byte-hex-string-here" } } } } }

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "electron": { "command": "npx", "args": ["-y", "electron-mcp-server"], "env": { "SECURITY_LEVEL": "balanced", "SCREENSHOT_ENCRYPTION_KEY": "your-32-byte-hex-string-here" } } } }

Global Installation

npm install -g electron-mcp-server

🔧 Available Tools

`launch_electron_app`

Launch an Electron application with debugging capabilities.

{ "appPath": "/path/to/electron-app", "devMode": true, // Enables Chrome DevTools Protocol on port 9222 "args": ["--enable-logging", "--dev"] }

Returns: Process ID and launch confirmation

`get_electron_window_info`

Get comprehensive window and target information via Chrome DevTools Protocol.

{ "includeChildren": true // Include child windows and DevTools instances }

Returns:

Window IDs, titles, URLs, and types
DevTools Protocol target information
Platform details and process information

`take_screenshot`

Capture high-quality screenshots using Playwright and Chrome DevTools Protocol.

{ "outputPath": "/path/to/screenshot.png", // Optional: defaults to temp directory "windowTitle": "My App" // Optional: target specific window }

Features:

Non-intrusive capture (doesn't bring window to front)
Works with any Electron app
Fallback to platform-specific tools if needed

`send_command_to_electron`

Execute JavaScript commands in the running Electron application via WebSocket.

{ "command": "eval", // Built-in commands: eval, get_title, get_url, click_button, console_log "args": { "code": "document.querySelector('button').click(); 'Button clicked!'" } }

Enhanced UI Interaction Commands:

find_elements: Analyze all interactive UI elements with their properties and positions
click_by_text: Click elements by their visible text, aria-label, or title (more reliable than selectors)
fill_input: Fill input fields by selector, placeholder text, or associated label text
select_option: Select dropdown options by value or visible text
get_page_structure: Get organized overview of all page elements (buttons, inputs, selects, links)
get_title: Get document title
get_url: Get current URL
get_body_text: Extract visible text content
click_button: Click buttons by CSS selector (basic method)
console_log: Send console messages
eval: Execute custom JavaScript code

Recommended workflow: Use get_page_structure first to understand available elements, then use specific interaction commands like click_by_text or fill_input.

`read_electron_logs`

Stream application logs from main process, renderer, and console.

{ "logType": "all", // Options: "all", "main", "renderer", "console" "lines": 50, // Number of recent lines "follow": false // Stream live logs }

`close_electron_app`

Gracefully close the Electron application.

{ "force": false // Force kill if unresponsive }

`build_electron_app`

Build Electron applications for distribution.

{ "projectPath": "/path/to/project", "platform": "darwin", // win32, darwin, linux "arch": "x64", // x64, arm64, ia32 "debug": false }

💡 Usage Examples

Smart UI Interaction Workflow

// 1. First, understand the page structure await send_command_to_electron({ command: 'get_page_structure', }); // 2. Click a button by its text (much more reliable than selectors) await send_command_to_electron({ command: 'click_by_text', args: { text: 'Login', // Finds buttons containing "Login" in text, aria-label, or title }, }); // 3. Fill inputs by their label or placeholder text await send_command_to_electron({ command: 'fill_input', args: { text: 'username', // Finds input with label "Username" or placeholder "Enter username" value: 'john.doe@example.com', }, }); await send_command_to_electron({ command: 'fill_input', args: { text: 'password', value: 'secretpassword', }, }); // 4. Select dropdown options by visible text await send_command_to_electron({ command: 'select_option', args: { text: 'country', // Finds select with label containing "country" value: 'United States', // Selects option with this text }, }); // 5. Take a screenshot to verify the result await take_screenshot();

Advanced Element Detection

// Find all interactive elements with detailed information await send_command_to_electron({ command: 'find_elements', }); // This returns detailed info about every clickable element and input: // { // "type": "clickable", // "text": "Submit Form", // "id": "submit-btn", // "className": "btn btn-primary", // "ariaLabel": "Submit the registration form", // "position": { "x": 100, "y": 200, "width": 120, "height": 40 }, // "visible": true // }

Automated UI Testing

// Launch app in development mode await launch_electron_app({ appPath: '/path/to/app', devMode: true, }); // Take a screenshot await take_screenshot(); // Click a button programmatically await send_command_to_electron({ command: 'eval', args: { code: "document.querySelector('#submit-btn').click()", }, }); // Verify the result await send_command_to_electron({ command: 'get_title', });

Development Debugging

// Get window information const windowInfo = await get_electron_window_info(); // Extract application data await send_command_to_electron({ command: 'eval', args: { code: 'JSON.stringify(window.appState, null, 2)', }, }); // Monitor logs await read_electron_logs({ logType: 'all', lines: 100, });

Performance Monitoring

// Get system information await send_command_to_electron({ command: 'eval', args: { code: '({memory: performance.memory, timing: performance.timing})', }, }); // Take periodic screenshots for visual regression testing await take_screenshot({ outputPath: '/tests/screenshots/current.png', });

🏗️ Architecture

Chrome DevTools Protocol Integration

Universal Compatibility: Works with any Electron app that has remote debugging enabled
Real-time Communication: WebSocket-based command execution with the renderer process
No App Modifications: Zero changes required to target applications

Process Management

Clean Environment: Handles ELECTRON_RUN_AS_NODE and other environment variables
Resource Tracking: Monitors PIDs, memory usage, and application lifecycle
Graceful Shutdown: Proper cleanup and process termination

Cross-Platform Support

macOS: Uses Playwright CDP with screencapture fallback
Windows: PowerShell-based window detection and capture
Linux: X11 window management (planned)

🧪 Development

Prerequisites

Node.js 18+
TypeScript 4.5+
Electron - Required for running and testing Electron applications
# Install Electron globally (recommended) npm install -g electron # Or install locally in your project npm install electron --save-dev

Target Application Setup

For the MCP server to work with your Electron application, you need to enable remote debugging. Add this code to your Electron app's main process:

const { app } = require('electron'); const isDev = process.env.NODE_ENV === 'development' || process.argv.includes('--dev'); // Enable remote debugging in development mode if (isDev) { app.commandLine.appendSwitch('remote-debugging-port', '9222'); }

Alternative approaches:

# Launch your app with debugging enabled electron . --remote-debugging-port=9222 # Or via npm script npm run dev -- --remote-debugging-port=9222

Note: The MCP server automatically scans ports 9222-9225 to detect running Electron applications with remote debugging enabled.

Setup

git clone https://github.com/halilural/electron-mcp-server.git cd electron-mcp-server npm install npm run build # Run tests npm test # Development mode with auto-rebuild npm run dev

Testing

The project includes comprehensive test files for React compatibility:

# Run React compatibility tests cd tests/integration/react-compatibility electron test-react-electron.js

See tests/integration/react-compatibility/README.md for detailed testing instructions and scenarios.

React Compatibility

This MCP server has been thoroughly tested with React applications and handles common React patterns correctly:

✅ React Event Handling: Properly handles preventDefault() in click handlers
✅ Form Input Detection: Advanced scoring algorithm works with React-rendered inputs
✅ Component Interaction: Compatible with React components, hooks, and state management

Project Structure

src/ ├── handlers.ts # MCP tool handlers ├── index.ts # Server entry point ├── tools.ts # Tool definitions ├── screenshot.ts # Screenshot functionality ├── utils/ │ ├── process.ts # Process management & DevTools Protocol │ ├── logs.ts # Log management │ └── project.ts # Project scaffolding └── schemas/ # JSON schemas for validation

🔐 Security & Best Practices

Sandboxed Execution: All JavaScript execution is contained within the target Electron app
Path Validation: Only operates on explicitly provided application paths
Process Isolation: Each launched app runs in its own process space
No Persistent Access: No permanent modifications to target applications

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Before reporting issues: Please use the standardized ISSUE_TEMPLATE.md for proper bug reporting format. For React compatibility problems or similar technical issues, also review REACT_COMPATIBILITY_ISSUES.md for detailed debugging examples, including proper command examples, error outputs, and reproduction steps.

Fork the repository
Create a feature branch (git checkout -b feature/awesome-feature)
Commit your changes (git commit -m 'Add awesome feature')
Push to the branch (git push origin feature/awesome-feature)
Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

☕ Support

If this project helped you, consider buying me a coffee! ☕

Ko-fi

Your support helps me maintain and improve this project. Thank you! 🙏

🙏 Acknowledgments

Model Context Protocol - Standardized AI-application interface
Chrome DevTools Protocol - Universal debugging interface
Playwright - Reliable browser automation
Electron - Cross-platform desktop applications

🔗 Links

GitHub Repository
NPM Package
Model Context Protocol
Chrome DevTools Protocol Docs
Issue Template - Standardized bug reporting format
React Compatibility Issues Documentation - Technical debugging guide for React applications

Ready to supercharge your Electron development with AI-powered automation? Install the MCP server and start building smarter workflows today! 🚀

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

A Model Context Protocol server that provides comprehensive Electron application automation, debugging, and observability capabilities through Chrome DevTools Protocol integration.

Related MCP Servers

Chrome MCP Server
lxe
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to control Chrome browsers through the Chrome DevTools Protocol, allowing for navigation, clicking, typing, and extracting page information.
Last updated -
42
Electron Terminal MCP Server
nexon33
A
security
A
license
A
quality
A Model Context Protocol server that enables clients to interact with a system terminal running in an Electron application, allowing for executing commands, managing terminal sessions, and retrieving output programmatically.
Last updated -
5
4
MIT License
Chrome Debug MCP Server
Rainmen-xia
A
security
A
license
A
quality
A Model Context Protocol server that connects to Chrome debugging ports, enabling browser automation with persistent login sessions.
Last updated -
10
29
8
MIT License
Snowfort Circuit MCPofficial
snowfort-ai
-
security
F
license
-
quality
A comprehensive Model Context Protocol (MCP) server suite that enables AI coding agents to automate both web browsers and Electron desktop applications with auto-snapshots and element references.
Last updated -
46

View all related MCP servers

Appeared in Searches

MCP tools for monitoring application memory and CPU usage