playwright-parallel-mcp

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.

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.

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)

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:

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="[email protected]"]
[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

Comparison

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