Playwright MCP Orchestrator
MCP server: Playwright MCP Orchestrator
Installation
npx playwright-mcp-orchestratorAsk AI about Playwright MCP Orchestrator
Powered by Claude Β· Grounded in docs
I know everything about Playwright MCP Orchestrator. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Playwright Orchestrator
A production-ready Model Context Protocol (MCP) server that enables multiple concurrent Claude Code sessions to use Playwright browser automation simultaneously. Each session gets its own isolated browser environment in a dedicated Docker container.
π― Why This Orchestrator?
The Problem: The standard Playwright MCP server can only handle one browser session at a time. When multiple Claude Code users try to use Playwright simultaneously, they share the same Chromium instance, leading to:
- Browser state conflicts between users
- Navigation interference (User A's actions affect User B's browser)
- Session data leakage and security concerns
- "No open pages available" errors when contexts collide
The Solution: This orchestrator creates dedicated Playwright containers for each Claude Code session:
- β True isolation - Each user gets their own browser instance
- β Concurrent usage - Multiple Claude sessions can run Playwright simultaneously
- β Session persistence - Browser state maintained across multiple tool calls
- β Scalable - Spin up as many instances as needed
- β Secure - No data leakage between different users
π Quick Setup for Claude Code
1. Install and Build
git clone <repository>
cd playwright-mcp-orchestrator
npm install
npm run build
2. Add to Claude Code
# Recommended: Using npx for automatic updates
claude mcp add playwright-orchestrator --scope user -- npx mcp-playwright-orchestrator
# Alternative: Direct path
claude mcp add playwright-orchestrator --scope user -- node /path/to/playwright-mcp-orchestrator/dist/index.js
3. Test Integration
Start using Playwright tools in Claude Code - each session will automatically get its own isolated browser container!
ποΈ High-Level Architecture
βββββββββββββββββββ STDIO βββββββββββββββββββββββ STDIO βββββββββββββββββββββββ
β Claude Code βββββββββββββββΊβ βββββββββββββββΊβ Docker Container β
β Session A β β MCP Orchestrator β β Playwright Instance β
βββββββββββββββββββ β β β A β
β β’ Client Cache β βββββββββββββββββββββββ
βββββββββββββββββββ STDIO β β’ Session Manager β STDIO βββββββββββββββββββββββ
β Claude Code βββββββββββββββΊβ β’ Resource Pool βββββββββββββββΊβ Docker Container β
β Session B β β β’ Instance Tracker β β Playwright Instance β
βββββββββββββββββββ βββββββββββββββββββββββ β B β
βββββββββββββββββββββββ
Key Components:
MCP Orchestrator (This Project)
- Receives MCP requests from Claude Code sessions
- Creates and manages dedicated Playwright containers
- Caches client connections for session persistence
- Provides transparent tool proxying to containers
Session Isolation
- Each Claude Code session gets a unique
instanceId - One persistent Docker container per instanceId
- Browser state isolated between different users
- Automatic cleanup when sessions end
Docker Container Management
- Uses official
mcr.microsoft.com/playwright/mcp:latestimage - STDIO-based communication (not HTTP)
- Networking configured for external website access
- Auto-removal with
--rmflag for cleanup
π οΈ Core Features
- MCP 2025 Compliance: Built with official
@modelcontextprotocol/sdk - Session Persistence: Browser state maintained across multiple tool calls
- Concurrent Sessions: Multiple Claude Code users can use Playwright simultaneously
- Docker Integration: Automated container lifecycle management
- Transparent Proxying: All Playwright MCP tools work exactly the same
- Resource Management: Configurable limits, health monitoring, graceful shutdown
- Production Ready: Full TypeScript, structured logging, error handling
π οΈ Installation & Setup
# Clone and install dependencies
git clone <repository>
cd playwright-mcp-orchestrator
npm install
# Build the project
npm run build
# Run in development
npm run dev
# Run tests
npm test
π¦ Quick Start
Via stdio (recommended for Claude)
npm run dev
Via HTTP server
npm run dev -- --http
# or
PORT=3000 npm run dev -- --http
π§ MCP Tools Available
The orchestrator provides 4 management tools that work transparently with Claude Code:
list_tools (Auto-creates instance)
Lists all available Playwright tools. If no instanceId provided, automatically creates a new dedicated browser instance for your session.
Claude Code Usage: Automatically called when you first use Playwright Returns: 21+ browser automation tools (navigate, click, type, screenshot, etc.)
call_tool (Core browser automation)
Executes any Playwright tool on your dedicated browser instance.
Examples in Claude Code:
- "Navigate to https://example.com" β
browser_navigate - "Click the login button" β
browser_click - "Type my email in the form" β
browser_type - "Take a screenshot" β
browser_take_screenshot - "Get page content" β
browser_snapshot
list_instances (Management)
Shows all running browser instances across all Claude Code sessions.
check_health (Diagnostics)
Checks if a specific browser instance is healthy and responsive.
π‘ User Experience
From Claude Code perspective, you just use Playwright tools normally:
You: "Navigate to GitHub and take a screenshot"
Claude Code automatically:
1. Calls list_tools β Creates your dedicated browser instance
2. Calls browser_navigate β Opens GitHub in YOUR browser
3. Calls browser_take_screenshot β Captures YOUR browser state
Multiple users can do this simultaneously without interfering with each other!
βοΈ Configuration
Configure via environment variables:
# Docker settings
PLAYWRIGHT_MCP_IMAGE=mcr.microsoft.com/playwright/mcp:latest
EXPOSED_PORT_IN_CONTAINER=3001
CONTAINER_NETWORK=mcp-network
# Orchestrator settings
ORCHESTRATOR_HOST=127.0.0.1
MAX_INSTANCES=10
LOG_LEVEL=info
# Security
ENABLE_DNS_REBINDING_PROTECTION=true
ALLOWED_HOSTS=127.0.0.1,localhost
# Timeouts
HEALTH_CHECK_TIMEOUT_MS=2500
CONTAINER_STARTUP_TIMEOUT_MS=30000
# Rate limiting
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX=100
π§ͺ Testing
The project includes comprehensive test files for validation:
Critical Regression Tests
# Test the exact user scenario that was originally failing
node test-mcp-debug.js
# Complete end-to-end system test
node test-final-verification.js
# Multi-session isolation (security test)
node test-multi-session.js
# Docker networking validation
node test-networking-fix.js
Test Coverage
- Session Persistence: Ensures browser state persists across tool calls
- Container Isolation: Validates multiple Claude sessions don't interfere
- Docker Integration: Tests container creation, networking, and cleanup
- MCP Protocol: Verifies transparent tool proxying and error handling
Development Testing
# Build and run unit tests
npm run build
npm test
# Run tests in watch mode
npm run test:watch
π³ Docker Usage
The orchestrator manages Playwright MCP containers with:
- Security: Non-root users, no new privileges, resource limits
- Isolation: Custom networks, port randomization
- Monitoring: Health checks, graceful shutdown
- Auto-cleanup: Containers removed on exit
Container Requirements
The orchestrator uses the official Microsoft Playwright MCP Docker image:
- Image:
mcr.microsoft.com/playwright/mcp:latest - Protocol: Model Context Protocol (MCP) over HTTP
- Endpoint:
/mcpfor MCP JSON-RPC requests - Tools: Browser automation via Playwright (navigate, click, fill, etc.)
- Capabilities: Headless browser automation with structured accessibility data
π Security Features
- DNS Rebinding Protection: Validates Host headers
- Rate Limiting: Configurable request limits
- CORS: Secure cross-origin resource sharing
- Helmet: Security headers (CSP, HSTS, etc.)
- Container Security: Non-root execution, read-only filesystem where possible
π Monitoring & Observability
- Structured Logging: JSON logs with Winston
- Health Endpoints:
/healthfor load balancers - Metrics: Instance counts, uptime tracking
- Error Tracking: Detailed error context
π Production Deployment
Environment Setup
# Production settings
NODE_ENV=production
LOG_LEVEL=info
ENABLE_DNS_REBINDING_PROTECTION=true
ALLOWED_HOSTS=your-domain.com
# Resource limits
MAX_INSTANCES=50
RATE_LIMIT_MAX=1000
Docker Compose Example
version: '3.8'
services:
orchestrator:
build: .
environment:
- NODE_ENV=production
- MAX_INSTANCES=20
volumes:
- /var/run/docker.sock:/var/run/docker.sock
ports:
- "3000:3000"
restart: unless-stopped
π€ Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
π License
MIT License - see LICENSE file for details.
π Troubleshooting
Common Issues
"No open pages available" after navigation
- Issue: Browser can't access external websites due to Docker networking
- Solution: The orchestrator includes networking fixes automatically
- Test: Run
node test-networking-fix.jsto verify
"Connection closed" errors
- Issue: Client caching not working properly
- Solution: Restart orchestrator, check logs for container conflicts
- Test: Run
node test-mcp-debug.jsto verify the fix
Multiple users interfering with each other
- Issue: Sessions not properly isolated
- Solution: Each Claude Code session should get unique instanceId
- Test: Run
node test-multi-session.jsto verify isolation
Docker permission errors
# Ensure Docker socket access
sudo usermod -aG docker $USER
# Then logout/login or restart terminal
Container cleanup issues
# Clean up any stuck containers
docker kill $(docker ps -q --filter "ancestor=mcr.microsoft.com/playwright/mcp:latest") 2>/dev/null || true
Debug Mode
LOG_LEVEL=debug npm run dev
# Watch orchestrator logs for detailed container and session info
Monitoring Containers
# Watch containers being created/destroyed
watch -n 2 "docker ps --filter 'ancestor=mcr.microsoft.com/playwright/mcp:latest'"
