Electron Mcp Server

Electron MCP Server

[](https://github.com/laststance/electron-mcp-server/blob/master/LICENSE) [](https://www.npmjs.com/package/@laststance/electron-mcp-server) [](https://modelcontextprotocol.io)

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.

> ⚠️ Breaking change in v2.0 — the single send_command_to_electron tool has been split into ~40 individual electron_* tools (e.g. electron_click_by_selector, electron_fill_input). This dramatically improves LLM tool selection accuracy. Read [MIGRATION.md](./MIGRATION.md) for the full v1 → v2 mapping. v1.x stays available via npm install @laststance/electron-mcp-server@^1.7.

Demo

See the Electron MCP Server in action:

[](https://vimeo.com/1104937830)

🎬 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", "@laststance/electron-mcp-server@latest"],
        "env": {
          "SECURITY_LEVEL": "balanced",
          "SCREENSHOT_ENCRYPTION_KEY":"your-32-byte-hex-string"
        }
      }
    }
  }
}

Claude Desktop Configuration:

{
  "mcpServers": {
    "electron": {
      "command": "npx",
      "args": ["-y", "@laststance/electron-mcp-server@latest"],
      "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 [SECURITYCONFIG.md](./SECURITYCONFIG.md) for detailed security documentation.

🎯 Proper MCP Usage Guide

⚠️ Critical: Argument Structure

> Heads up — v1 docs from here onward. The sections below (argument > structure, send_command_to_electron tool reference, and the long form of > the v1 examples) describe the v1 API. v2.0 splits that single tool into > ~40 individual electron_* tools. If you are on v2, jump straight to > [MIGRATION.md](./MIGRATION.md) — the v2 tools take their arguments > top-level, so the structure pitfall described here no longer applies.

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 after previous click" | Same target clicked within ~1s (click_by_selector) / ~2s (click_by_text) — intentional React anti-double-submit debounce | Serialize calls (await each) or pass a different selector / text | | Cmd+A / Cmd+C / Cmd+V does nothing in electron_press_key | macOS OS-level text-editing shortcuts are bypassed by CDP Input.dispatchKeyEvent (synthetic events only — same constraint as Playwright) | Use electron_eval with el.select() / el.setSelectionRange(...) / navigator.clipboard.*; for app-level hotkeys use electron_send_keyboard_shortcut |

🛠️ 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)

[](https://insiders.vscode.dev/redirect/mcp/install?name=electron&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22electron-mcp-server%22%5D%7D)

Add to your VS Code MCP settings:

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

Claude Code (CLI)

The fastest way to add this server to Claude Code is the claude mcp add command. Options come before the server name; the -- separator marks where the spawn command begins.

Project-scoped (lives in .mcp.json, share via git):

claude mcp add electron-mcp \
  --env SECURITY_LEVEL=balanced \
  -- npx -y @laststance/electron-mcp-server@latest

User-scoped (available across every project on this machine):

claude mcp add --scope user electron-mcp \
  --env SECURITY_LEVEL=balanced \
  -- npx -y @laststance/electron-mcp-server@latest

Verify:

claude mcp list

> 💡 On Windows, prefix the spawn command with cmd /c (e.g. -- cmd /c npx -y @laststance/electron-mcp-server@latest) so the npx shim resolves correctly.

Cursor IDE Integration

Cursor IDE supports MCP servers through its configuration file. Add to your Cursor MCP settings:

Location:

• macOS/Linux: ~/.cursor/mcp_config.json or ~/.config/cursor/mcp_config.json
• Windows: %APPDATA%\Cursor\mcp_config.json

Configuration:

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

Setup Steps:

1. Open Cursor IDE
2. Go to Settings → Features → Model Context Protocol
3. Enable MCP support
4. Add the configuration above to your MCP config file
5. Restart Cursor IDE

Verify Installation:

# Check if MCP server is accessible
curl http://localhost:9222/json

Claude Desktop Integration

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

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

OpenAI Codex CLI

The Codex CLI registers MCP servers through ~/.codex/config.toml (CLI and IDE extension share the same file).

One-liner (preferred):

codex mcp add electron-mcp -- npx -y @laststance/electron-mcp-server@latest

Or edit ~/.codex/config.toml directly:

[mcp_servers.electron-mcp]
command = "npx"
args = ["-y", "@laststance/electron-mcp-server@latest"]

[mcp_servers.electron-mcp.env]
SECURITY_LEVEL = "balanced"

Codex launches the server automatically on session start and exposes its electron_* tools next to the built-ins.

Global Installation

npm install -g @laststance/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

> v1 only. Removed in v2. See [MIGRATION.md](./MIGRATION.md) for the > per-command replacement (electron_click_by_selector, electron_fill_input, > electron_eval, etc.).

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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: laststance
• Source: laststance/electron-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.