Playwright MCP

An MCP server that gives compatible clients structured control of a real Playwright browser for QA, scraping diagnostics, accessibility-minded inspection, and reproducible browser workflows.

Architecture

Transport entrypoints are thin:

• src/index.ts starts MCP over stdio.
• src/http.ts starts MCP over Streamable HTTP.
• src/server.ts builds one McpServer and registers all tools.

Core services own browser state:

• BrowserManager serializes tool execution, launches browsers lazily, and manages contexts/pages.
• TelemetryStore captures console messages, page errors, failed requests, and recent network events.
• Tool modules register focused actions and depend only on the public browser/session APIs.

Tool groups:

• Browser/context/page lifecycle
• Navigation and waiting
• Interaction
• Inspection and screenshots
• Assertions
• Diagnostics, tracing, and storage

Install

npm install
npm run install-browsers
npm run build

Run

npm start

HTTP transport:

npm run start:http

Default HTTP endpoint: http://127.0.0.1:8931/mcp.

Production Controls

Configuration is environment-driven:

• PLAYWRIGHT_MCP_HTTP_TOKEN: require Authorization: Bearer <token> for HTTP mode.
• PLAYWRIGHT_MCP_HTTP_ALLOWED_ORIGINS: comma-separated CORS allowlist.
• PLAYWRIGHT_MCP_ALLOWED_ORIGINS: comma-separated browser navigation allowlist.
• PLAYWRIGHT_MCP_BLOCKED_ORIGINS: comma-separated browser navigation blocklist.
• PLAYWRIGHT_MCP_ALLOW_EVALUATE: enable the dangerous evaluate tool. Default: false.
• PLAYWRIGHT_MCP_ALLOW_DOWNLOADS: enable download tools and accepting downloads. Default: false.
• PLAYWRIGHT_MCP_ALLOW_UPLOADS: enable upload tools. Default: false.
• PLAYWRIGHT_MCP_ARTIFACT_DIR: screenshots, traces, PDFs, downloads, and storage state directory. Default: ./artifacts.
• PLAYWRIGHT_MCP_MAX_CONTEXTS: browser context cap. Default: 8.
• PLAYWRIGHT_MCP_MAX_PAGES: page cap. Default: 32.
• PLAYWRIGHT_MCP_DEFAULT_TIMEOUT_MS: default Playwright timeout. Default: 30000.
• PLAYWRIGHT_MCP_LOG_LEVEL: debug, info, warn, or error.

HTTP mode should use PLAYWRIGHT_MCP_HTTP_TOKEN before binding to anything other than localhost.

MCP client config

Examples are available in examples/:

• claude_config.json
• cursor_mcp.json
• codex_config.toml
• cline_mcp_settings.json
• opencode_config.json

Development

npm run check