Playwright MCP Server

Extracts structured, deterministic page snapshots using Playwright's accessibility tree API rather than vision-based screenshot analysis. The server traverses the DOM and builds a machine-readable representation of interactive elements, text content, and page structure that LLMs can process directly without requiring vision model inference. This approach provides consistent, repeatable page understanding across different viewport sizes and rendering states.

Implements the Model Context Protocol specification through @modelcontextprotocol/sdk, registering approximately 70 tool handlers that translate MCP callTool requests directly into Playwright API calls. Each tool is defined with JSON schema for parameter validation and type safety. The server uses a transport abstraction layer that allows the same tool logic to work over STDIO (local process spawning), HTTP/SSE (remote servers), or WebSocket (extension bridge mode), enabling flexible deployment patterns.

Executes arbitrary JavaScript code in the page context and returns results as JSON-serializable values. The server can evaluate expressions, call page functions, and manipulate the DOM directly. Supports passing arguments to scripts and handling both synchronous and asynchronous JavaScript execution. Results are serialized and returned to the LLM, enabling complex page interactions beyond standard Playwright APIs. Includes error handling for script execution failures and timeouts.

Provides a configuration system (config.d.ts) that allows customization of browser launch options, server behavior, and network settings. Configuration includes browser type selection (Chromium, Firefox, WebKit), headless mode, proxy settings, authentication credentials, and server-level options (port, transport type). Configuration is applied at server startup and persists for the lifetime of the server instance. Supports both environment variable and configuration file-based setup.

Implements a Chrome DevTools Protocol (CDP) relay system that enables the extension bridge mode to connect to existing Chrome/Edge browser tabs. The relay intercepts CDP messages from the extension, translates them to Playwright API calls, and returns results back through the CDP channel. Connection management handles WebSocket lifecycle, message serialization, and error recovery. The extension can connect to the MCP server via WebSocket and control browser tabs without launching new processes.

Distributes the Playwright MCP server as a Docker image at mcr.microsoft.com/playwright/mcp with multi-architecture support (amd64/arm64). The Docker image includes the CLI binary, all browser binaries (Chromium, Firefox, WebKit), and runtime dependencies, enabling containerized deployment without local installation. The image supports both STDIO and HTTP/SSE transport modes, allowing flexible orchestration in Kubernetes, Docker Compose, or other container platforms. Container startup is optimized for quick browser initialization.

Exposes a programmatic API through createConnection() function that allows direct SDK integration without spawning a separate process. Developers can instantiate an MCP server instance in their Node.js application and invoke browser automation tools directly. The API returns a connection object with methods for calling tools, managing browser lifecycle, and handling events. Supports both synchronous and asynchronous tool invocation with proper error handling and resource cleanup.

Supports two distinct execution modes: (1) Standalone Server Mode launches and manages its own browser instance via Playwright, and (2) Extension Bridge Mode connects to existing Chrome/Edge tabs via Chrome DevTools Protocol (CDP). The extension bridge uses a CDP relay system to intercept and translate browser commands, allowing LLMs to control already-open browser sessions without launching new instances. Both modes expose the same tool interface, enabling seamless switching between managed and existing browser contexts.

Provides tools for clicking, typing, and interacting with page elements using accessibility-aware selector strategies. The server maps element references from the accessibility tree to Playwright locators, enabling LLMs to target elements by role, label, or text content rather than fragile CSS selectors. Supports multi-step interactions like filling forms, submitting buttons, and navigating through dynamic content while maintaining context about element accessibility properties.

Captures full-page and viewport-specific screenshots with support for device emulation (mobile, tablet, desktop viewports). The server can configure viewport dimensions, device pixel ratio, and user agent strings before capturing, enabling testing across different device contexts. Screenshots are returned as base64-encoded PNG data that can be processed by vision models or stored for debugging. Supports both full-page scrolling captures and viewport-only snapshots.

Runs automated accessibility audits on pages using Playwright's built-in accessibility scanning capabilities. The server can detect common accessibility violations (missing alt text, low contrast, missing labels, keyboard navigation issues) and report them with severity levels and remediation guidance. Audits are performed without external dependencies, using Playwright's native accessibility analysis engine. Results are structured as JSON with violation details, affected elements, and impact assessment.

Provides tools for navigating to URLs, waiting for page loads, and managing navigation state. The server supports multiple wait strategies: wait for network idle, wait for specific selectors, wait for navigation completion, and timeout-based waits. Navigation commands return page load metrics (load time, resource count) and can detect navigation failures or timeouts. Supports both standard navigation and history-based navigation (back/forward).

Automates form filling by accepting structured data (key-value pairs or JSON objects) and mapping them to form fields identified by accessibility attributes. The server validates input types (text, number, email, date) and applies appropriate input methods (type, select, check/uncheck). Supports multi-step form filling, conditional field handling, and form submission. Returns validation errors and field-specific feedback when data doesn't match expected formats.

Manages browser contexts (isolated browser sessions with separate cookies, storage, and cache) and pages within contexts. The server can create multiple contexts for parallel testing, manage authentication state across contexts, and persist/restore context state (cookies, local storage, session storage). Supports context-level configuration (viewport, user agent, geolocation, permissions) and enables testing of multi-user scenarios or parallel workflows. Context state can be saved and restored for reproducible testing.

Intercepts and mocks network requests at the page level, allowing modification of request headers, blocking of specific URLs, and stubbing of responses. The server can configure network interception rules before page load, capture actual network traffic for analysis, and inject mock responses for testing error scenarios or offline behavior. Supports pattern-based URL matching and response templating. Network interception is context-specific and can be configured per page or globally.