Skip to main content
Glama
playwright-parallel-mcp
by sumyapp

playwright-parallel-mcp

CI Coverage Status npm version

English | 日本語 | 中文

A Model Context Protocol (MCP) server that enables AI agents to control multiple independent browser instances in parallel.

The Problem

Existing browser automation MCP servers (Chrome DevTools MCP, Playwright MCP) share a single browser instance across all sessions, causing conflicts when multiple AI agents try to use them simultaneously.

Related MCP server: mcp-browser-parallel

The Solution

playwright-parallel-mcp creates isolated browser instances for each session by spawning independent MCP backend processes, enabling true parallel browser automation.

Architecture (v0.3.0+)

playwright-parallel-mcp uses a wrapper architecture that spawns child MCP server processes for each session:

┌─────────────────────────────────────────────────────────────────┐
│              playwright-parallel-mcp (Wrapper)                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Session Manager                                         │    │
│  │  - Session lifecycle management                          │    │
│  │  - Tool routing with sessionId                           │    │
│  │  - Automatic cleanup                                     │    │
│  └─────────────────────────────────────────────────────────┘    │
└───────────────┬─────────────────────┬─────────────────────┬─────┘
                │                     │                     │
                ▼                     ▼                     ▼
    ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
    │  Session A        │ │  Session B        │ │  Session C        │
    │  ┌─────────────┐  │ │  ┌─────────────┐  │ │  ┌─────────────┐  │
    │  │ MCP Backend │  │ │  │ MCP Backend │  │ │  │ MCP Backend │  │
    │  │ (Child      │  │ │  │ (Child      │  │ │  │ (Child      │  │
    │  │  Process)   │  │ │  │  Process)   │  │ │  │  Process)   │  │
    │  └──────┬──────┘  │ │  └──────┬──────┘  │ │  └──────┬──────┘  │
    │         │         │ │         │         │ │         │         │
    │         ▼         │ │         ▼         │ │         ▼         │
    │  ┌─────────────┐  │ │  ┌─────────────┐  │ │  ┌─────────────┐  │
    │  │  Browser    │  │ │  │  Browser    │  │ │  │  Browser    │  │
    │  │  Instance   │  │ │  │  Instance   │  │ │  │  Instance   │  │
    │  └─────────────┘  │ │  └─────────────┘  │ │  └─────────────┘  │
    └───────────────────┘ └───────────────────┘ └───────────────────┘

Key Benefits

  • Process-Level Isolation: Each session runs in a separate OS process

  • Backend Agnostic: Works with any MCP browser automation server

  • Always Latest: Uses @latest versions, no dependency updates needed

  • Automatic Cleanup: Sessions are cleaned up on timeout or process exit

Session Isolation Guarantee

Each session is 100% isolated. This is architecturally guaranteed by process-level separation.

Resource

Isolated?

How

Browser Process

✅ Yes

Separate OS process per session

Cookies

✅ Yes

Separate browser instance

localStorage

✅ Yes

Separate browser instance

DOM

✅ Yes

Separate page instance

Navigation History

✅ Yes

Separate page instance

Features

  • Parallel Sessions - Each session gets its own browser instance

  • Process Isolation - True isolation via separate OS processes

  • Pluggable Backends - Use Playwright MCP, Chrome DevTools MCP, or any npm package

  • Dynamic Tools - Tools are dynamically loaded from the backend

  • Low Overhead - Only 3 session management tools + backend tools

  • Free & Local - No cloud service required

Installation

With Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "playwright-parallel": {
      "command": "npx",
      "args": ["playwright-parallel-mcp"]
    }
  }
}

With npm

npm install -g playwright-parallel-mcp
playwright-parallel-mcp

Available Tools

Session Management (3 tools)

Tool

Description

create_session

Create a new isolated browser session

close_session

Close a browser session and terminate its backend process

list_sessions

List all active sessions

Backend Tools (dynamically loaded)

All tools from the backend MCP server are automatically available with an added sessionId parameter. For example, with the default Playwright backend:

Tool

Description

browser_navigate

Navigate to a URL

browser_snapshot

Get accessibility tree snapshot

browser_click

Click an element

browser_fill

Fill a form input

browser_type

Type text

browser_press_key

Press keyboard key

...

And many more from @playwright/mcp

Usage Examples

Basic Navigation

User: Open example.com and take a screenshot

Claude: I'll create a browser session and navigate to example.com.

[create_session] -> sessionId: "abc123"
[browser_navigate sessionId="abc123" url="https://example.com"]
[browser_screenshot sessionId="abc123"]

Parallel Sessions

User: Compare the homepage of two websites side by side

Claude: I'll create two browser sessions in parallel.

[create_session] -> sessionId: "session-a"
[create_session] -> sessionId: "session-b"
[browser_navigate sessionId="session-a" url="https://example.com"]
[browser_navigate sessionId="session-b" url="https://google.com"]
[browser_snapshot sessionId="session-a"]
[browser_snapshot sessionId="session-b"]

Form Interaction

User: Fill out the login form

Claude: I'll fill in the form fields and submit.

[browser_fill sessionId="abc123" element="Email input" ref="e1" value="user@example.com"]
[browser_fill sessionId="abc123" element="Password input" ref="e2" value="***"]
[browser_click sessionId="abc123" element="Submit button" ref="e3"]

Backend Configuration

Default Backend (Playwright)

By default, playwright-parallel-mcp uses @playwright/mcp as the backend:

{
  "mcpServers": {
    "playwright-parallel": {
      "command": "npx",
      "args": ["playwright-parallel-mcp"]
    }
  }
}

Chrome DevTools Backend

To use Chrome DevTools MCP instead:

{
  "mcpServers": {
    "playwright-parallel": {
      "command": "npx",
      "args": ["playwright-parallel-mcp"],
      "env": {
        "MCP_BACKEND": "chrome-devtools"
      }
    }
  }
}

Custom Backend

Any npm package that provides an MCP server can be used:

{
  "mcpServers": {
    "playwright-parallel": {
      "command": "npx",
      "args": ["playwright-parallel-mcp"],
      "env": {
        "MCP_BACKEND": "my-custom-mcp-server"
      }
    }
  }
}

Environment Variables

Variable

Default

Description

MCP_BACKEND

playwright

Backend MCP server: playwright, chrome-devtools, or any npm package

MAX_SESSIONS

10

Maximum number of concurrent browser sessions

SESSION_TIMEOUT_MS

3600000

Session inactivity timeout (1 hour)

Comparison

Feature

Chrome DevTools MCP

Playwright MCP

This Project

Parallel Sessions

No

No

Yes

Session Isolation

No

No

Yes (Process-level)

Backend Choice

Chrome only

Playwright only

Any MCP server

Tool Updates

Manual

Manual

Automatic (@latest)

Cost

Free

Free

Free

Requirements

  • Node.js 20+

  • Backend browser requirements (e.g., Playwright browsers)

Development

git clone https://github.com/sumyapp/playwright-parallel-mcp
cd playwright-parallel-mcp
pnpm install
pnpm build
pnpm start

Running Tests

pnpm test

Project Structure

src/
  index.ts           # MCP server entry point with tool definitions
  session-manager.ts # Session lifecycle management
  mcp-client.ts      # MCP client for child process communication
  types.ts           # Type definitions and backend configuration

Security Warning

This MCP server provides powerful browser automation capabilities.

  • Backend tools like browser_evaluate execute arbitrary JavaScript

  • File upload tools can access the file system

  • Only use in controlled environments with trusted clients

License

MIT

Available Tools

27 tools
browser_clickC

Perform click on a web page

Inputs: target (required), sessionId (required), button, element, +2 more.

browser_closeC

Close the page

Inputs: sessionId (required).

browser_console_messagesC

Returns all console messages

Inputs: level (required), sessionId (required), all, filename.

browser_dragB

Perform drag and drop between two elements

Inputs: endTarget (required), sessionId (required), startTarget (required), endElement, +1 more.

browser_dropA

Drop files or MIME-typed data onto an element, as if dragged from outside the page. At least one of "paths" or "data" must be provided.

Inputs: target (required), sessionId (required), data, paths, +1 more.

browser_evaluateC

Evaluate JavaScript expression on page or element

Inputs: function (required), sessionId (required), target, element, +1 more.

browser_file_uploadC

Upload one or multiple files

Inputs: sessionId (required), paths.

browser_fill_formC

Fill multiple form fields

Inputs: fields (required), sessionId (required).

browser_findA

Search the accessibility snapshot of the current page for text or a regular expression. Returns matching snapshot nodes with a few lines of surrounding context (like search snippets), each shown under its path from the root of the tree, which is cheaper than capturing the whole snapshot when you only need to locate an element and its ref.

Inputs: sessionId (required), text, regex.

browser_handle_dialogD

Handle a dialog

Inputs: accept (required), sessionId (required), promptText.

browser_hoverC

Hover over element on page

Inputs: target (required), sessionId (required), element.

browser_navigateC

Navigate to a URL

Inputs: url (required), sessionId (required).

browser_navigate_backA

Go back to the previous page in the history

Inputs: sessionId (required).

browser_network_requestA

Returns full details (headers and body) of a single network request, or a single part if part is set. Use the number from browser_network_requests.

Inputs: index (required), sessionId (required), part, filename.

browser_network_requestsA

Returns a numbered list of network requests since loading the page. Use browser_network_request with the number to get full details.

Inputs: static (required), sessionId (required), filter, filename.

browser_press_keyC

Press a key on the keyboard

Inputs: key (required), sessionId (required).

browser_resizeC

Resize the browser window

Inputs: width (required), height (required), sessionId (required).

browser_run_code_unsafeA

Run a Playwright code snippet. Unsafe: executes arbitrary JavaScript in the Playwright server process and is RCE-equivalent.

Inputs: sessionId (required), code, filename.

browser_select_optionC

Select an option in a dropdown

Inputs: target (required), values (required), sessionId (required), element.

browser_snapshotB

Capture accessibility snapshot of the current page, this is better than screenshot

Inputs: sessionId (required), boxes, depth, target, +1 more.

browser_tabsB

List, create, close, or select a browser tab.

Inputs: action (required), sessionId (required), url, index.

browser_take_screenshotA

Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.

Inputs: type (required), scale (required), sessionId (required), target, +3 more.

browser_typeC

Type text into editable element

Inputs: text (required), target (required), sessionId (required), slowly, +2 more.

browser_wait_forA

Wait for text to appear or disappear or a specified time to pass

Inputs: sessionId (required), text, time, textGone.

close_sessionA

Close a browser session and terminate its backend process

Inputs: sessionId (required).

create_sessionA

Create a new isolated browser session. Each session runs an independent MCP backend process.

Inputs: backend.

list_sessionsA

List all active browser sessions

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 27 tools

    Disambiguation5/5

    Each tool targets a distinct operation in browser automation: navigation, clicking, typing, selecting, dragging, dropping, uploading, snapshotting, network inspection, and console messages. Even similar tools like browser_evaluate and browser_run_code_unsafe are clearly differentiated by their execution context (page vs server).

    Naming Consistency3/5

    Most tools follow a 'browser_' prefix, but the suffix is inconsistent: some use verbs (navigate, click, hover) while others use nouns (snapshot, screenshot, console_messages). Session management tools (create_session, list_sessions, close_session) deviate entirely from the prefix pattern, creating a mixed convention.

    Tool Count3/5

    With 27 tools, the server is on the heavier side, but the breadth covers a full browser automation workflow including interactions, network, console, dialogs, and session management. The count is justified by the domain, though it exceeds the typical well-scoped range.

    Completeness4/5

    The tool set covers the core browser automation lifecycle: navigation, interactions, snapshots, waiting, tabs, file uploads, and network inspection. Minor gaps like forward navigation or explicit scrolling can be worked around via browser_evaluate or browser_navigate, so there are no dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Multi-session browser MCP server that gives AI agents up to 15 fully-isolated browsers running in parallel. 36 tools including navigation, extraction, network intercept, stealth, and self-improvement. Each session has its own cookies, storage, and fingerprint so agents never collide.
      37
      110 npm
      5
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Multi-instance parallel browser MCP server that manages multiple isolated browser instances in a single Chrome process with automatic login state cloning, allowing parallel independent operations across instances.
      36
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A local, open-source MCP server that enables AI clients to control multiple isolated Chromium browser sessions concurrently, with explicit session and page addressing and independent state.
      35
      49 npm
      3
      Apache 2.0