Electron MCP

MCP (Model Context Protocol) server for testing Electron applications using Playwright. Enables AI models like Claude to interact with and test your Electron apps.

🚀 Quick Start

# Run directly with npx
npx @teapotz/electron-mcp

# Or install globally
npm install -g @teapotz/electron-mcp
electron-mcp

Features

• Two Connection Modes
  • CDP Mode: Connect to a running Electron app via Chrome DevTools Protocol
  • Launch Mode: Launch a fresh Electron app instance for testing
• Full Playwright API: screenshot, click, fill, type, hover, press, wait, evaluate, and more
• Accessibility Snapshots: Get the accessibility tree for element discovery
• Main Process Access: Execute code in Electron's main process (launch mode only)

How It Works

User <--> AI Model (Claude) <--> MCP Protocol <--> electron-mcp <--> Electron App

1. User: "Click the login button and fill in the email field"
2. AI Model: Determines which MCP tools to use
3. MCP Protocol: Standardized communication
4. electron-mcp: Executes Playwright commands on the Electron app
5. Electron App: Actions are performed in the actual application

Configuration

Claude Desktop / MCP Clients

Add to your MCP configuration file:

{
  "mcpServers": {
    "electron-test": {
      "command": "npx",
      "args": ["@teapotz/electron-mcp"]
    }
  }
}

OpenCode

{
  "mcp": {
    "electron-test": {
      "type": "local",
      "command": ["npx", "@teapotz/electron-mcp"],
      "enabled": true
    }
  }
}

Connection Modes

CDP Mode (Recommended for Development)

Connect to an already running Electron app with remote debugging enabled:

# Start your Electron app with debugging port
electron your-app --remote-debugging-port=9222

# Or with electron-vite
electron-vite dev -- --remote-debugging-port=9222

Then use the connect tool:

connect({ port: 9222 })

Advantages:

• Works with your existing dev workflow
• App state preserved between tests
• Hot reload still works

Launch Mode

Launch a fresh Electron app instance:

launch({ appPath: "./out/main/index.js" })

# With headless mode for CI
launch({ appPath: "./out/main/index.js", headless: true })

Advantages:

• Clean state for each test
• Access to main process via evaluateMain
• Can pass custom environment variables
• Supports headless mode for CI/automation

Headless Mode (CI/Automation)

Launch Mode

Pass headless: true to run without a visible window:

launch({ appPath: "./out/main/index.js", headless: true })

CDP Mode

Start your Electron app with headless flags before connecting:

# Option 1: Electron headless flag (Electron 28+)
electron your-app --headless=new --remote-debugging-port=9222

# Option 2: xvfb (Linux) - virtual framebuffer
xvfb-run electron your-app --remote-debugging-port=9222

# Option 3: xvfb with specific display (CI environments)
Xvfb :99 -screen 0 1920x1080x24 &
DISPLAY=:99 electron your-app --remote-debugging-port=9222

Then connect normally:

connect({ port: 9222 })

Available Tools

Connection

| Tool | Description | | ------------ | --------------------------------------- | | connect | Connect to running app via CDP | | disconnect | Disconnect from CDP (app keeps running) | | launch | Launch new Electron app instance | | close | Close launched app |

Interaction

| Tool | Description | | -------------- | ----------------------------------- | | click | Click an element | | dblclick | Double-click an element | | fill | Fill text into input (clears first) | | type | Type text character by character | | hover | Hover over an element | | press | Press keyboard key | | drag | Drag and drop | | selectOption | Select from dropdown |

Scroll

| Tool | Description | | ----------------- | ------------------------------------ | | scroll | Scroll using mouse wheel (deltaX/Y) | | scrollTo | Scroll to absolute position | | scrollIntoView | Scroll element into view |

Mouse

| Tool | Description | | -------------- | ---------------------------------------- | | mouseMove | Move mouse cursor to coordinates | | mouseDown | Press mouse button down | | mouseUp | Release mouse button | | mouseClick | Click at specific coordinates |

Inspection

| Tool | Description | | -------------- | -------------------------------------- | | screenshot | Take screenshot (returns base64 image) | | snapshot | Get accessibility tree | | getText | Get element text content | | getAttribute | Get element attribute | | isVisible | Check if element is visible | | count | Count matching elements |

Advanced

| Tool | Description | | -------------- | ------------------------------------------- | | wait | Wait for element state | | evaluate | Run JS in renderer process | | evaluateMain | Run code in main process (launch mode only) |

Selectors

Supports all Playwright selectors:

# CSS selectors
[data-testid="submit-btn"]
.my-class
#my-id

# Text selectors
text=Submit
text="Exact Match"

# Role selectors
role=button[name="Submit"]

# Combining
.form >> text=Submit

Usage Examples

Basic Test Flow

1. connect({ port: 9222 })
2. snapshot()  // See the page structure
3. click('[data-testid="login-btn"]')
4. fill('[data-testid="email"]', '[email protected]')
5. fill('[data-testid="password"]', 'password123')
6. click('text=Sign In')
7. wait({ selector: '[data-testid="dashboard"]' })
8. screenshot()

Main Process Access (Launch Mode)

// Get app version
evaluateMain({
  script: "({ app }) => app.getVersion()",
});

// Show dialog
evaluateMain({
  script: "({ dialog }) => dialog.showMessageBox({ message: 'Hello!' })",
});

With AI Assistant

You can ask Claude or other AI assistants to test your Electron app:

Connect to my Electron app running on port 9222 and:
1. Take a screenshot of the current state
2. Click the "Settings" button in the sidebar
3. Change the theme to dark mode
4. Verify the theme changed by checking the background color

Tips for Testable Electron Apps

1. Add data-testid attributes to important elements
2. Enable remote debugging in development: --remote-debugging-port=9222
3. Use semantic HTML for better accessibility snapshots
4. Keep selectors stable - prefer data-testid over classes

Development

# Clone repository
git clone https://github.com/teapotz/electron-mcp.git
cd electron-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js