Electron MCP Server

A Model Context Protocol (MCP) server for testing Electron applications using Playwright. This server enables AI coding tools like Cursor and Claude Code to interact with Electron applications for automated testing and development.

Features

• Electron App Lifecycle: Launch and manage Electron applications programmatically
• CDP Connection: Connect to running Electron apps via Chrome DevTools Protocol with retry logic and IPv6/IPv4 fallback
• Element Interaction: Click, fill, select, and interact with UI elements
• Navigation: Navigate to URLs and manage page state, with CDP-backed navigation history tools
• Window Management: Control Electron main windows (focus, minimize, maximize)
• Main Process Access: Execute scripts in the Electron main process
• Visual Testing: Capture screenshots and compare against baselines
• Accessibility Testing: Retrieve accessibility tree information, structured accessibility snapshots, and role-based interactions
• Session Management: Multiple concurrent test sessions with UUID tracking
• Advanced CDP Features: Network emulation, geolocation override, device metrics, performance monitoring, navigation history
• Code Generation: Record user flows and export Playwright tests
• Robust Error Handling: Categorized errors with automatic classification and retry recommendations

Installation

Using npm (Recommended)

npm install -g @kanishka-namdeo/electron-mcp-server

From Source

git clone https://github.com/kanishka-namdeo/electron-mcp-server.git
cd electron-mcp-server
npm install
npm run build

Usage

Running the Server

# Development mode with hot reload
npm run dev

# Production mode
npm run start

# Build TypeScript
npm run build

AI Tool Integration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "electron-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@kanishka-namdeo/electron-mcp-server"
      ],
      "env": {
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Or using a global installation:

{
  "mcpServers": {
    "electron-mcp-server": {
      "command": "electron-mcp-server",
      "env": {
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "electron-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@kanishka-namdeo/electron-mcp-server"
      ]
    }
  }
}

Or for global installation:

{
  "mcpServers": {
    "electron-mcp-server": {
      "command": "electron-mcp-server"
    }
  }
}

Available Tools

The Electron MCP Server provides 44 tools across 6 categories:

App Lifecycle (4 tools)

Tool	Description
launch_electron_app	Launch an Electron application
connect_to_electron_cdp	Connect to a running Electron app via CDP
close_session	Close a test session
list_sessions	List all active sessions

Element Interaction (10 tools)

Tool	Description
navigate	Navigate to a URL
click	Click on an element
fill	Fill an input field with text
select	Select an option from a dropdown
get_text	Get text content of an element
screenshot	Take a screenshot of the page or element
wait_for_selector	Wait for an element to appear
execute	Execute JavaScript in the renderer process
get_page_info	Get page URL and title

Main Process & Window Control (8 tools)

Tool	Description
execute_main_process_script	Execute JavaScript in the main process
get_main_window_info	Get window information
focus_main_window	Focus the main window
minimize_main_window	Minimize the main window
maximize_main_window	Maximize the main window
get_unresponsive_callstack	Report capability info for unresponsive renderer callstack capture in Electron 34+ apps
get_shared_dictionary_info	Report capability info for HTTP shared dictionary compression in Electron 34+ apps
clear_shared_dictionary_cache	Report capability info for clearing shared dictionary cache in Electron 34+ apps

Visual Testing & Accessibility (11 tools)

Tool	Description
take_screenshot	Capture a screenshot
capture_element_screenshot	Screenshot a specific element
compare_screenshots	Compare against a baseline
get_viewport_size	Get current viewport dimensions
set_viewport_size	Set viewport dimensions
get_accessibility_tree	Retrieve accessibility tree
get_accessibility_snapshot	Get Playwright accessibility snapshot for the current page
find_accessible_node	Find nodes by accessibility role/name with optional fuzzy matching
interact_accessible_node	Click or fill accessible nodes by role/name

Advanced CDP Features (12 tools)

Tool	Description
get_protocol_info	Get CDP protocol version and browser info
emulate_network_conditions	Emulate slow/offline network
reset_network_conditions	Reset to default network settings
set_geolocation	Override geolocation
clear_geolocation	Remove geolocation override
set_device_metrics	Emulate mobile device
get_console_messages	Capture console logs
get_performance_metrics	Get performance metrics
clear_browser_cache	Clear cache and cookies
get_user_agent	Get current user agent
get_navigation_history	Get navigation history entries via CDP
restore_navigation_history	Restore a history entry via CDP

Codegen & Recording

Tool	Description
start_recording	Start recording a flow for a session
stop_recording	Stop recording and return structured steps
export_recording_as_test	Export recorded steps as a Playwright test snippet

Links

• npm: https://www.npmjs.com/package/@kanishka-namdeo/electron-mcp-server
• Repository: https://github.com/kanishka-namdeo/electron-mcp-server
• Issues: https://github.com/kanishka-namdeo/electron-mcp-server/issues

Development

Testing

The project has a comprehensive test suite with multiple categories:

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Run E2E tests only (requires running Electron app)
npm run test:e2e

# Run compliance tests only
npm run test:compliance

# Run tests in watch mode
npm run test:watch

Linting

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

Type Checking

npm run typecheck

Building

# Build TypeScript
npm run build

# Development mode with hot reload
npm run dev

# Production mode
npm start

Project Structure

electron-mcp-server/
├── src/
│   ├── core/
│   │   ├── errors.ts              # Custom error classes
│   │   ├── errors-enhanced.ts     # Enhanced error handling with classification
│   │   ├── cdp-utils.ts           # CDP connection utilities with retry logic
│   │   ├── connection-health.ts   # Connection health monitoring
│   │   ├── logger.ts              # Pino logging setup
│   │   └── types.ts               # TypeScript type definitions
│   ├── session/
│   │   ├── session-manager.ts   # Session lifecycle management
│   │   └── index.ts
│   ├── tools/
│   │   ├── handlers/
│   │   │   ├── app-lifecycle.ts       # App launch and CDP connection
│   │   │   ├── element-interaction.ts # Click, fill, select, navigate
│   │   │   ├── main-process.ts        # Window control and main process scripts
│   │   │   ├── visual-testing.ts      # Screenshots, viewport, accessibility
│   │   │   └── cdp-advanced.ts        # Network, geolocation, device metrics
│   │   ├── tools.ts                   # Tool definitions
│   │   ├── validation.ts              # Zod schemas
│   │   ├── validation-enhanced.ts     # Enhanced validation schemas
│   │   └── index.ts
│   └── index.ts                       # Main MCP server
├── tests/
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   ├── e2e/               # End-to-end tests
│   ├── compliance/        # MCP protocol compliance tests
│   ├── utils/             # Test utilities
│   └── fixtures/          # Test fixtures
├── test-app/              # Electron test application
├── .trae/
│   └── docs/              # Phase 1 & 2 documentation
├── CHANGELOG.md           # Version history
├── LICENSE                # MIT License
├── package.json
├── tsconfig.json
└── vitest.config.ts

Environment Variables

• LOG_LEVEL: Logging level (default: info)
• NODE_ENV: Environment (default: production)

License

MIT