playwright-mcp

Extracts structured, deterministic page snapshots using Playwright's accessibility tree instead of screenshots, enabling LLMs to process semantic page structure directly without vision models. The server traverses the DOM via Playwright's internal accessibility APIs and serializes interactive elements (buttons, inputs, links) with their roles, labels, and coordinates into a machine-readable format that preserves spatial relationships and semantic meaning.

Implements ~70 tool handlers that translate MCP callTool requests into Playwright API calls via a schema-based function registry. Each tool is registered with a JSON schema defining parameters, return types, and descriptions; the server validates incoming requests against these schemas and dispatches to the appropriate Playwright method, supporting both synchronous operations (click, type, navigate) and asynchronous workflows (wait for conditions, screenshot capture).

Intercepts and modifies network requests and responses using Playwright's route API. The server can block requests, modify request headers or bodies, mock responses, or log network activity. This enables testing of error scenarios, performance optimization, and API mocking without modifying the application code.

Provides a Chrome extension that bridges existing browser tabs to the MCP server via Chrome DevTools Protocol (CDP). The extension establishes a WebSocket connection to the server, relays CDP commands, and enables control of user-visible browser tabs without launching a new browser instance. The server implements a CDP relay layer that translates MCP tool calls into CDP commands and routes responses back through the extension.

Manages multiple browser pages and contexts within a single MCP server session, enabling workflows that span multiple tabs or windows. The server maintains a page registry, allows switching between pages, and supports context-specific operations (cookies, storage, permissions). This enables complex workflows like multi-step form filling across pages, parallel page monitoring, or testing multi-tab interactions.

Implements automatic retry logic and error recovery for transient failures (network timeouts, stale elements, temporary unavailability). The server catches common Playwright errors, applies exponential backoff, and retries operations up to a configurable limit. This reduces the need for explicit error handling in LLM workflows and improves reliability of long-running automation.

Distributes the MCP server as a Docker image at mcr.microsoft.com/playwright/mcp with multi-architecture support (amd64, arm64). The image includes Node.js, Playwright browser binaries, and the MCP server CLI, enabling deployment in containerized environments without local installation. The image supports both STDIO and HTTP/SSE transports for flexible deployment patterns.

Supports two distinct execution modes: Standalone Server Mode launches and manages its own browser instance via Playwright, while Extension Bridge Mode connects to existing Chrome/Edge tabs via Chrome DevTools Protocol (CDP). The server abstracts these modes through a unified browser context management layer, allowing the same tool handlers to work regardless of whether the browser is managed by the server or controlled via CDP relay from a browser extension.

Implements the MCP Server specification with transport abstraction, allowing the same server logic to operate over STDIO (for local process spawning), HTTP/SSE (for remote servers), or WebSocket (for extension bridge connections). The transport layer decouples the tool handler logic from the underlying communication protocol, enabling deployment flexibility: STDIO for local MCP clients, HTTP/SSE for cloud deployments, and WebSocket for browser extension communication.

Manages browser contexts, pages, and sessions through a configuration system that accepts browser options (headless mode, viewport, user agent), server options (timeout, proxy), and network options (request interception, response mocking). The server instantiates browser contexts based on this schema, maintains isolated page sessions, and applies configuration at both the browser and context levels, enabling multi-page workflows with independent state management.

Implements high-level interaction tools that locate elements by selector, role, or text and perform actions (click, type, select options, submit forms). The server uses Playwright's locator API to find elements with built-in retry logic and waits for elements to be actionable (visible, enabled) before interacting, handling common edge cases like stale elements, overlapping content, and dynamic rendering.

Provides navigation tools that handle page transitions, URL changes, and load state management. The server supports navigation via URL, back/forward buttons, and page reloads, with configurable wait conditions (wait for load, wait for specific elements, wait for network idle). The implementation uses Playwright's waitForLoadState and waitForSelector APIs to ensure pages are fully loaded before returning control to the LLM.

Captures full-page or viewport screenshots in PNG format, with optional element highlighting to mark specific elements (buttons, inputs, links) with bounding boxes or visual indicators. The server uses Playwright's screenshot API with configurable options (full page, viewport only, omit animations) and can overlay element locations to help LLMs understand which elements are interactive.

Extracts form fields, input values, and structured content from pages using Playwright's DOM query APIs. The server can retrieve form state (input values, selected options, checked checkboxes), extract tables and lists as structured data, and parse page content into semantic units. This enables LLMs to understand page structure without vision models and to verify form state before submission.

Executes arbitrary JavaScript code in the browser context and returns results as JSON-serializable values. The server uses Playwright's evaluate API to run code with access to the page's window object, allowing LLMs to perform custom DOM queries, trigger events, or manipulate page state. Results are automatically serialized to JSON, with support for primitives, objects, and arrays.