playwright-mcp-electron

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

playwright-mcp-electron

★ 17 Open GitHub ↗

Playwright Tools for MCP with Electron Support

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## Playwright MCP with Electron Support

A Model Context Protocol (MCP) server that provides browser and **Electron application** automation capabilities using [Playwright](https://playwright.dev). This enhanced fork of the [official Playwright MCP](https://github.com/microsoft/playwright-mcp) includes full support for testing and automating Electron desktop applications alongside traditional web browser automation.

### Key Features

- **Electron support**. Test and automate Electron desktop applications with dedicated tools.
- **Fast and lightweight**. Uses Playwright's accessibility tree, not pixel-based input.
- **LLM-friendly**. No vision models needed, operates purely on structured data.
- **Deterministic tool application**. Avoids ambiguity common with screenshot-based approaches.
- **Main process access**. Execute JavaScript in Electron's main process.
- **Window management**. Control and interact with multiple Electron windows.

### Requirements
- Node.js 18 or newer
- VS Code, Cursor, Windsurf, Claude Desktop, Goose or any other MCP client

### Getting started

First, install the Playwright Electron MCP server with your client. A typical configuration looks like this:

```js
{
  "mcpServers": {
    "playwright-electron": {
      "command": "npx",
      "args": [
        "@robertn702/playwright-mcp-electron@latest"
      ]
    }
  }
}
```

By default, this runs in Electron mode. To use regular browser automation, add `--browser chrome` or `--browser firefox`.

[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright-electron%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540robertn702%252Fplaywright-mcp-electron%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright-electron%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540robertn702%252Fplaywright-mcp-electron%2540latest%2522%255D%257D)

<details><summary>Install in VS Code</summary>

You can also install the Playwright MCP server using the VS Code CLI:

```bash
# For VS Code
code --add-mcp '{"name":"playwright-electron","command":"npx","args":["@robertn702/playwright-mcp-electron@latest"]}'
```

After installation, the Playwright Electron MCP server will be available for use with your GitHub Copilot agent in VS Code.
</details>

<details>
<summary>Install in Cursor</summary>

#### Click the button to install:

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)

#### Or install manually:

Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx @robertn702/playwright-mcp-electron`. You can also verify config or add command like arguments via clicking `Edit`.

```js
{
 "mcpServers": {
 "playwright": {
 "command": "npx",
 "args": [
 "@robertn702/playwright-mcp-electron@latest"
 ]
 }
 }
}
```
</details>

<details>
<summary>Install in Windsurf</summary>

Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use following configuration:

```js
{
 "mcpServers": {
 "playwright": {
 "command": "npx",
 "args": [
 "@robertn702/playwright-mcp-electron@latest"
 ]
 }
 }
}
```
</details>

<details>
<summary>Install in Claude Desktop</summary>

Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use following configuration:

```js
{
 "mcpServers": {
 "playwright-electron": {
 "command": "npx",
 "args": [
 "@robertn702/playwright-mcp-electron@latest"
 ]
 }
 }
}
```
</details>

<details>
<summary>Install in Claude Code</summary>

Use the Claude Code CLI to add the Playwright Electron MCP server:

```bash
claude mcp add playwright-electron npx @robertn702/playwright-mcp-electron@latest
```
</details>

<details>
<summary>Install in Goose</summary>

#### Click the button to install:

[![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=%40robertn702%2Fplaywright-mcp-electron%40latest&id=playwright-electron&name=Playwright%20Electron&description=Interact%20with%20web%20pages%20and%20Electron%20apps%20through%20structured%20accessibility%20snapshots%20using%20Playwright)

#### Or install manually:

Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx @robertn702/playwright-mcp-electron`. Click "Add Extension".
</details>

<details>
<summary>Install in Qodo Gen</summary>

Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the following configuration:

```js
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@robertn702/playwright-mcp-electron@latest"
      ]
    }
  }
}
```

Click <code>Save</code>.
</details>

<details>
<summary>Install in Gemini CLI</summary>

Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use following configuration:

```js
{
 "mcpServers": {
 "playwright": {
 "command": "npx",
 "args": [
 "@robertn702/playwright-mcp-electron@latest"
 ]
 }
 }
}
```
</details>

### Configuration

Playwright MCP server supports following arguments. They can be provided in the JSON configuration above, as a part of the `"args"` list:

```
> npx @robertn702/playwright-mcp-electron@latest --help
 --allowed-origins <origins> semicolon-separated list of origins to allow the
 browser to request. Default is to allow all.
 --blocked-origins <origins> semicolon-separated list of origins to block the
 browser from requesting. Blocklist is evaluated
 before allowlist. If used without the allowlist,
 requests not matching the blocklist are still
 allowed.
 --block-service-workers block service workers
 --browser <browser> browser or chrome channel to use, possible
 values: chrome, firefox, webkit, msedge, electron.
 --browser-agent <endpoint> Use browser agent (experimental).
 --caps <caps> comma-separated list of capabilities to enable,
 possible values: tabs, pdf, history, wait, files,
 install. Default is all.
 --cdp-endpoint <endpoint> CDP endpoint to connect to.
 --config <path> path to the configuration file.
 --device <device> device to emulate, for example: "iPhone 15"
 --executable-path <path> path to the browser executable.
 --headless run browser in headless mode, headed by default
 --host <host> host to bind server to. Default is localhost. Use
 0.0.0.0 to bind to all interfaces.
 --ignore-https-errors ignore https errors
 --isolated keep the browser profile in memory, do not save
 it to disk.
 --image-responses <mode> whether to send image responses to the client.
 Can be "allow", "omit", or "auto". Defaults to
 "auto", which sends images if the client can
 display them.
 --no-sandbox disable the sandbox for all process types that
 are normally sandboxed.
 --output-dir <path> path to the directory for output files.
 --port <port> port to listen on for SSE transport.
 --proxy-bypass <bypass> comma-separated domains to bypass proxy, for
 example ".com,chromium.org,.domain.com"
 --proxy-server <proxy> specify proxy server, for example
 "http://myproxy:3128" or "socks5://myproxy:8080"
 --save-trace Whether to save the Playwright Trace of the
 session into the output directory.
 --storage-state <path> path to the storage state file for isolated
 sessions.
 --user-agent <ua string> specify user agent string
 --user-data-dir <path> path to the user data directory. If not
 specified, a temporary directory will be created.
 --viewport-size <size> specify browser viewport size in pixels, for
 example "1280, 720"
 --vision Run server that uses screenshots (Aria snapshots
 are used by default)
```

### User profile

You can run Playwright MCP with persistent profile like a regular browser (default), or in the isolated contexts for the testing sessions.

**Persistent profile**

All the logged in information will be stored in the persistent profile, you can delete it between sessions if you'd like to clear the offline state.
Persistent profile is located at the following locations and you can override it with the `--user-data-dir` argument.

```bash
# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile

# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile

# Linux
- ~/.cache/ms-playwright/mcp-{channel}-profile
```

**Isolated**

In the isolated mode, each session is started in the isolated profile. Every time you ask MCP to close the browser,
the session is closed and all the storage state for this session is lost. You can provide initial storage state
to the browser via the config's `contextOptions` or via the `--storage-state` argument. Learn more about the storage
state [here](https://playwright.dev/docs/auth).

```js
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@robertn702/playwright-mcp-electron@latest",
        "--isolated",
        "--storage-state={path/to/storage.json}"
      ]
    }
  }
}
```

### Configuration file

The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file
using the `--config` command line option:

```bash
npx @robertn702/playwright-mcp-electron@latest --config path/to/config.json
```

<details>
<summary>Configuration file schema</summary>

```typescript
{
  // Browser configuration
  browser?: {
    // Browser type to use (chromium, firefox, or webkit)
    browserName?: 'chromium' | 'firefox' | 'webkit';

// Keep the browser profile in memory, do not save it to disk.
    isolated?: boolean;

// Path to user data directory for browser profile persistence
    userDataDir?: string;

// Browser launch options (see Playwright docs)
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // Browser channel (e.g. 'chrome')
      headless?: boolean;      // Run in headless mode
      executablePath?: string; // Path to browser executable
      // ... other Playwright launch options
    };

// Browser context options
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... other Playwright context options
    };

// CDP endpoint for connecting to existing browser
    cdpEndpoint?: string;

// Remote Playwright server endpoint
    remoteEndpoint?: string;
  },

// Server configuration
  server?: {
    port?: number;  // Port to listen on
    host?: string;  // Host to bind to (default: localhost)
  },

// Enable vision mode (screenshots instead of accessibility snapshots)
  vision?: boolean;

// Directory for output files
  outputDir?: string;

// Network configuration
  network?: {
    // List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
    allowedOrigins?: string[];

// List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
 blockedOrigins?: string[];
 };
 
 /**
 * Whether to send image responses to the client. Can be "allow", "omit", or "auto". 
 * Defaults to "auto", images are omitted for Cursor clients and sent for all other clients.
 */
 imageResponses?: 'allow' | 'omit' | 'auto';
}
```
</details>

### Standalone MCP server

When running headed browser on system w/o display or from worker processes of the IDEs,
run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable SSE transport.

```bash
npx @robertn702/playwright-mcp-electron@latest --port 8931
```

And then in MCP client config, set the `url` to the SSE endpoint:

```js
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/sse"
    }
  }
}
```

<details>
<summary>Docker</summary>

**NOTE:** The Docker implementation only supports headless chromium at the moment.

```js
{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}
```

You can build the Docker image yourself.

```
docker build -t mcr.microsoft.com/playwright/mcp .
```
</details>

<details>
<summary>Programmatic usage</summary>

```js
import http from 'http';

import { createConnection } from '@robertn702/playwright-mcp-electron';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

// Creates a headless Playwright MCP server with SSE transport
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.sever.connect(transport);

// ...
});
```
</details>

### Electron Support

This enhanced version includes full support for Electron applications. By default, it runs in Electron mode.

#### Electron Configuration

To test an Electron app, ensure your configuration points to your app:

```js
{
  "mcpServers": {
    "playwright-electron": {
      "command": "npx",
      "args": [
        "@robertn702/playwright-mcp-electron@latest",
        "--executable-path", "/path/to/electron",
        "--cwd", "/path/to/your/electron/app"
      ]
    }
  }
}
```

Or use a config file:

```json
{
  "browser": {
    "browserName": "electron",
    "launchOptions": {
      "args": ["main.js"],
      "executablePath": "electron",
      "cwd": "/path/to/your/electron/app"
    }
  }
}
```

#### Electron-Specific Tools

In addition to all standard browser automation tools, Electron mode provides:

- **`electron_evaluate`** - Execute JavaScript in the main Electron process
- **`electron_windows`** - List all open Electron windows
- **`electron_first_window`** - Get the first window of the application
- **`electron_browser_window`** - Get BrowserWindow object for advanced control

#### Example Electron Usage

```javascript
// Launch your Electron app (happens automatically)
// Then use electron-specific tools:

// Execute code in main process
await electron_evaluate({ expression: "app.getVersion()" });

// Get all windows
await electron_windows();

// Interact with the UI using standard tools
await browser_click({ element: "Login button" });
```

### Tools

The tools are available in two modes:

1. **Snapshot Mode** (default): Uses accessibility snapshots for better performance and reliability
2. **Vision Mode**: Uses screenshots for visual-based interactions

To use Vision Mode, add the `--vision` flag when starting the server:

```js
{
  "mcpServers": {
    "playwright-electron": {
      "command": "npx",
      "args": [
        "@robertn702/playwright-mcp-electron@latest",
        "--vision"
      ]
    }
  }
}
```

Vision Mode works best with the computer use models that are able to interact with elements using
X Y coordinate space, based on the provided screenshot.

<details>
<summary>Interactions</summary>