Skip to main content
Glama
halilural

Electron MCP Server

by halilural
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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.

Related MCP server: Electron Terminal MCP Server

🎯 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:

  1. Copy .env.example to .env

  2. Set SECURITY_LEVEL to your desired level

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

  1. Inspect: Start with get_page_structure or debug_elements

  2. Target: Use specific selectors or text-based targeting

  3. Interact: Use the appropriate command with correct argument structure

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

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/awesome-feature)

  3. Commit your changes (git commit -m 'Add awesome feature')

  4. Push to the branch (git push origin feature/awesome-feature)

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

🔗 Links

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

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/halilural/electron-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server