playwright-mcp

Extracts structured, deterministic page snapshots using Playwright's accessibility tree API instead of vision-based screenshot analysis. The server traverses the DOM accessibility tree to generate JSON representations of page elements, their roles, states, and relationships, enabling LLMs to reason about page structure without requiring vision model inference. This approach provides deterministic, text-based page understanding that avoids the latency and cost of vision models.

Implements the Model Context Protocol specification by registering ~70 tool handlers that translate MCP callTool requests into Playwright API calls. The server uses @modelcontextprotocol/sdk to define tool schemas (name, description, input schema) and maps incoming MCP requests to corresponding Playwright methods, with support for async execution and structured error handling. This enables any MCP-compatible client (Claude Desktop, VS Code, Cursor, Windsurf) to invoke browser automation through a standardized protocol.

Implements capability gating where certain tools are only available when specific browser features are enabled or when running in particular modes. The server dynamically registers tools based on runtime capabilities (e.g., CDP relay tools only available in extension mode, certain tools disabled in headless mode). This prevents tool invocation errors by only exposing tools that can actually execute in the current environment.

Provides structured error reporting with stack traces, error codes, and contextual information for failed operations. The server catches exceptions from Playwright API calls and transforms them into MCP-compatible error responses with actionable debugging information. Error handling includes timeout errors, element not found errors, navigation failures, and JavaScript execution errors.

Implements Chrome DevTools Protocol relay that intercepts and forwards CDP messages between the browser extension and the MCP server. The extension bridge uses WebSocket to communicate with the server, translating MCP tool calls into CDP commands and CDP responses back into MCP results. This enables control of existing browser tabs without launching new processes, with the extension acting as a protocol bridge.

Provides containerized MCP server distribution through Azure Container Registry (mcr.microsoft.com/playwright/mcp) with multi-architecture support (amd64/arm64). The Docker image includes Node.js runtime, all Playwright browser binaries, and the MCP server CLI, enabling single-command deployment without local dependency installation. The image supports both standalone and extension bridge modes through environment configuration.

Exposes createConnection() function that enables programmatic instantiation of the MCP server without CLI invocation. The API allows TypeScript/JavaScript clients to create server instances with custom configuration, transport selection, and tool registration. This enables embedding the MCP server in larger applications or building custom MCP client wrappers.

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 relay. The extension mode uses a Chrome extension that bridges CDP messages between the browser and the MCP server, enabling control of already-open browser sessions without launching new processes. This dual-mode architecture allows deployment flexibility — either managed browser instances or connection to user-controlled browsers.

Abstracts transport layer to support stdio (for local process spawning), HTTP/SSE (for remote servers), and WebSocket (for extension bridge) protocols. The server implementation decouples transport from tool logic, allowing the same ~70 tool handlers to work across different deployment topologies. This enables deployment as a local CLI tool, containerized remote service, or browser extension backend without code duplication.

Manages isolated browser contexts with independent cookies, storage, and authentication state. The server maintains a registry of active browser contexts and pages, enabling multi-context automation where different contexts can have different authentication states or user agents. Context management includes automatic cleanup on disconnect and support for persistent context data across sessions via configuration.

Provides tools for clicking, typing, selecting, and submitting form elements with Playwright's built-in waiting and retry logic. The server exposes high-level interaction tools (click, fill, select) that handle element waiting, visibility checks, and error recovery automatically. Interactions are mapped to specific selectors (CSS, XPath, accessibility labels) and include support for keyboard shortcuts, file uploads, and multi-step form sequences.

Handles page navigation with configurable wait strategies (load, domcontentloaded, networkidle) and timeout management. The server provides tools for goto, reload, and back/forward navigation with support for waiting until specific network conditions are met. Navigation includes automatic handling of redirects, popup windows, and navigation errors with detailed error reporting.

Captures full-page or element-specific screenshots as PNG/JPEG with optional clipping and scaling. The server also provides DOM snapshot functionality that serializes the current DOM tree as HTML or JSON, enabling both visual and structural page analysis. Screenshots can be captured with specific viewport sizes and device emulation settings.

Executes arbitrary JavaScript in the page context with support for passing arguments and returning structured results. The server provides tools for evaluateHandle (returns object reference), evaluate (returns serialized result), and evaluateAll (evaluates on multiple elements). JavaScript execution includes automatic serialization of return values and error handling with stack traces.

Supports declarative configuration of browser launch options, network settings, and server behavior through a configuration file (config.d.ts schema). The configuration system allows specification of browser type, headless mode, proxy settings, user agent, viewport size, and network interception rules. Configuration is loaded at server startup and applied to all browser instances launched by the server.