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