Playwright MCP Server for Electron

A Model Context Protocol (MCP) server that provides Playwright automation capabilities specifically for Electron applications.

Overview

This project extends the functionality of the official Playwright MCP server to support Electron applications. While the official server focuses on web browsers, this implementation provides dedicated tools for automating Electron desktop applications.

This is a TypeScript project using Yarn as the package manager.

Background

Official Playwright MCP: Does not currently support Electron automation
Playwright Electron Support: Playwright has experimental support for Electron automation (documentation)
This Project: Bridges the gap by providing MCP tools specifically designed for Electron application automation

Technical Challenges

State Management Between Tool Calls

One of the key challenges in implementing this MCP server is maintaining Electron application instance references between tool calls. Unlike typical MCP tools that are stateless, Electron automation requires:

Keeping the ElectronApplication instance alive across multiple tool calls
Maintaining references to opened windows
Preserving application state and context
Handling cleanup when the session ends

Potential Solutions:

Instance caching with unique identifiers
Session-based state management
Automatic cleanup mechanisms
Connection pooling for multiple Electron apps

This architectural challenge needs to be carefully designed to ensure robust automation workflows while maintaining the MCP protocol's principles.

Analysis of Official Playwright MCP Server State Management

The official Playwright MCP server provides a proven reference for state management that we can adapt for Electron:

Key State Management Components:

Context Class - Central state manager that:
- Uses lazy initialization for browser contexts (_browserContextPromise)
- Maintains persistent browser context once created
- Manages array of Tab objects and current active tab
Connection-Level Isolation - Each MCP connection gets its own Context instance with isolated browser state
Persistent Browser Context - Browser context stays alive for entire session until explicitly closed, supporting both isolated and persistent modes
Tab State Management - Direct references to Playwright Page objects that persist throughout tab lifecycle
Modal State Tracking - Tracks blocking states (dialogs, file choosers) per-tab to prevent incompatible tool execution

Core Pattern: Lazy Initialization with Persistent References

The official server uses lazy initialization with persistent references - browser contexts are created on-demand then cached, and direct Playwright object references (Page, BrowserContext) are maintained across tool invocations.

Adaptation for Electron

For our Electron MCP server, we need similar patterns but adapted for:

ElectronApplication instances instead of browser contexts
Electron app lifecycle management instead of browser lifecycle
Multiple Electron windows instead of browser tabs
Electron-specific modal states and dialogs

Features

Electron-Specific Automation Tools

This server reproduces all the tools from the official Playwright MCP server but adapted for Electron applications:

Application Management
- Launch Electron applications
- Close Electron applications
- Application context evaluation
Window Management
- Access first window
- Multiple window handling
- Window navigation and control
UI Interaction
- Click elements
- Type text
- Key presses
- Mouse interactions (hover, drag)
- File uploads
- Dialog handling
Content Analysis
- Take screenshots
- Extract text content
- Element inspection
- Wait for conditions
Advanced Features
- HAR recording
- Video recording
- Trace collection
- Console monitoring

Supported Electron Versions

Based on Playwright's experimental Electron support:

v12.2.0+
v13.4.0+
v14+

Installation

yarn install

Usage

The server provides MCP tools that can be used by any MCP-compatible client to automate Electron applications.

Basic Example

// Launch an Electron app and interact with it
const electronApp = await electron.launch({ args: ['main.js'] });
const window = await electronApp.firstWindow();
await window.click('text=Click me');
await electronApp.close();

Tools Available

Application Control

electron_launch - Launch an Electron application
electron_close - Close the Electron application
electron_evaluate - Evaluate code in the Electron context

Window Management

electron_first_window - Get the first window
electron_new_window - Handle new windows
electron_window_list - List all windows

UI Interaction

electron_click - Click on elements
electron_type - Type text
electron_press_key - Press keyboard keys
electron_hover - Hover over elements
electron_drag - Drag and drop
electron_file_upload - Upload files
electron_handle_dialog - Handle dialogs

Content & Analysis

electron_screenshot - Take screenshots
electron_get_text - Extract text content
electron_wait_for - Wait for conditions
electron_console_log - Monitor console output

Recording & Debugging

electron_start_recording - Start video recording
electron_stop_recording - Stop video recording
electron_start_trace - Start trace recording
electron_stop_trace - Stop trace recording

Implementation Plan

Phase 1: Core Architecture Setup

Project Foundation
- Set up TypeScript project with Yarn
- Configure build system and development scripts
- Set up basic MCP server structure
State Management Layer
- Implement ElectronContext class (analogous to official server's Context)
- Create ElectronWindow class (analogous to Tab)
- Implement lazy initialization for ElectronApplication instances
- Add connection-level state isolation

Phase 2: Application Lifecycle Management

ElectronApplication Management
- Implement electron_launch tool with configurable launch options
- Add persistent application instance caching
- Implement electron_close tool with proper cleanup
- Handle application restart scenarios
Window Management
- Implement window discovery and tracking
- Add support for multiple window instances
- Create window switching and focus management
- Handle window lifecycle events (open/close)

Phase 3: Core Automation Tools

UI Interaction Tools
- electron_click - Element clicking with selector support
- electron_type - Text input with focus management
- electron_press_key - Keyboard interaction
- electron_hover - Mouse hover events
- electron_drag - Drag and drop operations
Content Analysis Tools
- electron_screenshot - Window/element screenshots
- electron_get_text - Text content extraction
- electron_wait_for - Condition waiting (elements, timeouts)
- electron_evaluate - JavaScript execution in renderer/main process

Phase 4: Advanced Features

Dialog and File Handling
- electron_handle_dialog - Modal dialog management
- electron_file_upload - File selection dialogs
- Modal state tracking system
Recording and Debugging
- electron_console_log - Console output monitoring
- electron_start_trace / electron_stop_trace - Trace recording
- electron_start_recording / electron_stop_recording - Video recording

Phase 5: Testing and Documentation

Test Suite
- Unit tests for state management
- Integration tests with sample Electron apps
- Error handling and edge case testing
Documentation and Examples
- API documentation for all tools
- Usage examples and best practices
- Migration guide from browser automation

Technical Implementation Details

State Management Architecture

// Core classes structure
class ElectronContext {
  private _electronAppPromise?: Promise<ElectronApplication>;
  private _windows: ElectronWindow[] = [];
  private _currentWindow?: ElectronWindow;
  private _modalStates = new Set<string>();
}

class ElectronWindow {
  private _page: Page;
  private _consoleMessages: any[] = [];
  private _requests: any[] = [];
}

Key Adaptations from Browser MCP

Replace BrowserContext with ElectronApplication
Replace Tab with ElectronWindow
Adapt navigation tools for Electron window management
Handle Electron-specific events and lifecycle

Tool Implementation Pattern

const electronClickTool = {
  name: 'electron_click',
  handle: async (context: ElectronContext, params) => {
    const window = await context.ensureWindow();
    await window.click(params.selector);
  }
};

Development

Prerequisites

Node.js 18+
Yarn package manager
TypeScript

Setup

yarn install
yarn build
yarn start

Project Structure

├── README.md
├── package.json
├── yarn.lock
├── tsconfig.json
├── src/
│   ├── index.ts          # Main MCP server
│   ├── electron-tools.ts # Electron automation tools
│   ├── state-manager.ts  # Instance state management
│   └── types.ts          # Type definitions
├── examples/
│   └── sample-usage.js   # Usage examples
└── tests/
    └── electron-test.ts  # Test cases

Building from Official Reference

This project uses the official Playwright MCP server as a reference implementation, adapting all browser-focused tools to work with Electron applications instead.

The key differences:

State Management: Electron instances must persist between tool calls
Application Lifecycle: Managing Electron app launch/close cycles
TypeScript Implementation: Full type safety for Electron APIs
Yarn Workspace: Modern package management

Known Issues

Ensure that nodeCliInspect (FuseV1Options.EnableNodeCliInspectArguments) fuse is not set to false in your Electron app
Some features may require specific Electron versions
Experimental support means API may change

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

MIT License

marcusdb/mcp-electron