Playwright MCP Wrapper

Secure MCP wrapper around @playwright/mcp with 20 tools (14 standard + 6 compound) — browser automation, REST API testing, and multi-step workflow engine.

Features

• 14 standard browser tools — navigate, click, type, screenshot, snapshot, evaluate, etc.
• 6 compound tools — browser_api_request, browser_collect_data, browser_workflow, api_workflow, start_recording, stop_recording
• Security layer — operation whitelist, domain whitelist, rate limiting, SSRF protection
• Variable engine — {{env.KEY}}, {{ctx.KEY}}, {{params.KEY}}, {{endpoints.KEY}} with nested resolution
• Workflow engine — multi-step browser + API workflows with JSONPath extraction
• Auto-archiving — screenshots, snapshots, API responses saved with date subdirs + retention
• Audit logging — JSONL audit trail per day
• Zero npm dependencies — pure Node.js built-ins + @playwright/mcp (installed separately)

Quick Start

1. Install

# Install globally
npm install -g playwright-mcp-wrapper

# Install runtime dependencies (@playwright/mcp + Firefox browser)
playwright-wrapper-install --browser firefox

Or from local source:

git clone <repo>
cd playwright-mcp-server
npm install -g .
playwright-wrapper-install --browser firefox

2. Configure Your MCP Agent

Claude Code (.mcp.json or Claude settings):

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

Cursor / VS Code Copilot (mcp.json):

{
  "mcpServers": {
    "playwright-wrapper": {
      "command": "node",
      "args": ["/path/to/playwright-mcp-server/bin/server.js"]
    }
  }
}

Continue.dev (config.json):

{
  "experimental": {
    "mcpServers": {
      "playwright-wrapper": {
        "command": "node",
        "args": ["/path/to/playwright-mcp-server/bin/server.js"]
      }
    }
  }
}

Generic MCP agent (any agent supporting mcpServers config):

{
  "mcpServers": {
    "playwright-wrapper": {
      "command": "node",
      "args": ["/path/to/playwright-mcp-server/bin/server.js"],
      "type": "stdio"
    }
  }
}

Note: Do NOT set PLAYWRIGHT_WRAPPER_INSTALL_DIR unless you need a custom install path. By default, resolveInstallDir() auto-detects the standalone path (~/.playwright-mcp-server/playwright/) and the IDE path (~/.codemoss/dependencies/playwright/). An incorrect or stale path will cause @playwright/mcp subprocess to fail, resulting in only 4 compound tools instead of all 20.

3. Verify

Call tools/list — should return 20 tools.

Try browser_navigate with URL https://example.com — opens Firefox.

Tools

Standard Browser Tools (14)

Tool	Description	Mode
browser_navigate	Navigate to a URL	Write
browser_click	Click an element	Write
browser_hover	Hover over an element	Read
browser_type	Type text into an input field	Write
browser_fill_form	Fill multiple form fields	Write
browser_select_option	Select a dropdown option	Write
browser_press_key	Press a keyboard key	Write
browser_snapshot	Get accessibility tree snapshot	Read
browser_take_screenshot	Take a page screenshot	Read
browser_evaluate	Execute JavaScript to extract/parse data (2 modes: browser + data)	Read
browser_wait_for	Wait for text/element	Read
browser_console_messages	Get console messages	Read
browser_network_requests	Get network requests	Read
browser_close	Close current page	Read

Compound Tools (6, enabled by default)

browser_api_request

Make independent REST API calls (not through browser). Supports GET/POST/PUT/DELETE with:

• Custom headers and body
• SSRF protection (blocks private IPs)
• Response validation (status codes, headers, body content)
• Auto-discovery of endpoints for reuse

browser_collect_data

Collect comprehensive data from current page in parallel:

• Screenshot, snapshot, network requests, console messages, performance metrics
• Structured report (JSON/Markdown/HTML)

browser_workflow

Execute multi-step workflows combining browser actions + API calls:

• Actions: navigate, click, type, wait_for, api_call, screenshot, collect, hover, select_option, press_key, scroll, evaluate
• Variable templating: {{env.KEY}}, {{ctx.KEY}}, {{params.KEY}}, {{endpoints.ID.url}}
• JSONPath extraction between steps: $.result.accessToken
• Template load/save for reuse

api_workflow

Multi-step pure API workflow with setup/teardown, retry, assertions, token chaining:

• Auth support: bearer, basic, apikey
• JSONPath extraction for step chaining
• Per-step retry with configurable on-fail behavior
• Ideal for login→fetch→logout flows and pagination

start_recording

Start recording API traffic from browser_api_request/api_workflow calls. Supports:

• Label-based session identification
• URL pattern filtering
• Optional browser network collection on stop

stop_recording

Stop recording API traffic, flush to disk. Returns summary with count, duration, endpoints.

Additional compound tools (import_openapi, list_endpoints, security_scan, generate_traffic_workflow) are available but disabled by default — enable via compoundTools in config.

Configuration

Config file: ~/.playwright-mcp-server/config.json (auto-created with defaults)

{
  "mode": "readwrite",
  "testMode": false,
  "whitelist": {
    "operations": {
      "allow": ["navigate", "screenshot", "snapshot", "click", "type", ...],
      "deny": ["evaluate", "press_key"],
      "readonly": ["screenshot", "snapshot", "hover", ...]
    },
    "domains": {
      "allow": ["*"],
      "deny": [],
      "mode": "deny-all-except-allowed"
    }
  },
  "limits": {
    "maxPages": 5,
    "rateLimit": 30,
    "rateWindowSec": 60
  },
  "audit": {
    "enabled": true,
    "dir": ".claude/playwright-audit/"
  },
  "output": {
    "enabled": true,
    "dir": ".claude/playwright-output/",
    "date_subdirs": true,
    "retention_days": 30
  },
  "repo": {
    "dir": ".claude/playwright-repo/",
    "env": null
  },
  "recording": {
    "enabled": true,
    "dir": ".claude/playwright-recording/",
    "max_entries_buffer": 500,
    "auto_flush": false,
    "include_request_bodies": true,
    "include_response_bodies": false,
    "max_body_size": 50000,
    "retention_days": 7
  },
  "compoundTools": {
    "browser_workflow": true,
    "api_workflow": true,
    "browser_api_request": true,
    "browser_collect_data": true,
    "start_recording": true,
    "stop_recording": true,
    "import_openapi": false,
    "list_endpoints": false,
    "security_scan": false,
    "generate_traffic_workflow": false
  }
}

Configuration Fields

Field	Type	Default	Description
mode	"readonly" / "readwrite"	"readwrite"	Operation mode
testMode	boolean	false	When enabled, exposes only 13 core browser tools — ideal for automated tests to reduce tool noise for the model
whitelist.operations.allow	string[]	[...]	Allowed browser operations
whitelist.operations.deny	string[]	["evaluate", "press_key"]	Denied operations
whitelist.domains.allow	string[]	["*"]	Allowed domains
limits.maxPages	number	5	Max concurrent browser pages
limits.rateLimit	number	30	Max operations per rate window
limits.rateWindowSec	number	60	Rate window in seconds
recording.enabled	boolean	true	Enable API traffic recording
compoundTools.*	boolean	varies	Enable/disable individual compound tools

CLI Options

node bin/server.js [--project-root <path>] [--config <path>] [--install-dir <path>]

Flag	Description	Default
--project-root	Project root for project-local config	None (standalone)
--config	Explicit config file path	~/.playwright-mcp-server/config.json
--install-dir	Path to @playwright/mcp install	~/.playwright-mcp-server/playwright/

Environment Variables

Variable	Description
PLAYWRIGHT_WRAPPER_CONFIG_PATH	Config file path
PLAYWRIGHT_WRAPPER_INSTALL_DIR	@playwright/mcp install directory

Asset Repository

When output.enabled and repo.dir are configured, the server auto-manages:

.playwright-mcp-server/
  repo/
    environments/    ← env configs (baseUrl, auth, factories)
    endpoints/       ← auto-discovered API endpoints
    pages/           ← auto-extracted page elements
    workflows/       ← reusable workflow templates
  output/
    YYYY-MM-DD/      ← timestamped output files
  audit/
    YYYY-MM-DD.jsonl ← JSONL audit trail

Architecture

Agent (Claude Code / Cursor / VS Code)
  │
  │ JSON-RPC 2.0 over stdio
  ▼
playwright-wrapper-mcp (bin/server.js)  ← this package
  │ Security: op whitelist, domain whitelist, rate limit, SSRF, audit
  │
  │ JSON-RPC 2.0 over stdio (via lib/mcp-client.js)
  ▼
@playwright/mcp (Firefox)  ← installed by bin/install.js

Zero MCP SDK dependency. All MCP protocol communication is hand-written JSON-RPC 2.0 over stdio using Node.js built-ins (node:readline).

License

MIT