playwright-parallel-mcp
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
@latestversions, 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_evaluateexecute arbitrary JavaScript - File upload tools can access the file system
- Only use in controlled environments with trusted clients
License
MIT
