mcp-playwright

Launches and maintains a single persistent Playwright browser instance (Chromium, Firefox, or WebKit) across multiple MCP tool invocations, with automatic page context management and error recovery. The server implements a global browser state pattern where the browser instance persists until explicitly closed, enabling multi-step workflows where each tool call operates on the same page context without re-initialization overhead.

Provides 8+ DOM interaction tools (click, fill, hover, drag, select, type, focus, blur) that use Playwright's selector engine to locate and manipulate elements. Each tool accepts CSS selectors, XPath, or Playwright's built-in locator strategies (role-based, text-based), validates element visibility and interactability before action, and returns detailed error messages if elements are not found or disabled.

Provides playwright_fill, playwright_select, and playwright_check tools that handle form input, dropdown selection, and checkbox/radio button toggling. The tools use Playwright's fill() for text inputs, selectOption() for <select> elements, and check()/uncheck() for checkboxes and radio buttons. Each tool validates element type before interaction and returns success/error status.

Provides playwright_switch_frame and playwright_get_frames tools that manage frame and iframe context switching. The tools use Playwright's frame() API to select frames by name, URL, or index, and return frame information (name, URL, parent frame). Enables automation of pages with iframes, nested frames, and cross-origin frames (if allowed by CORS).

Provides expect_response and assert_response tools that validate HTTP responses from API calls or page navigation. The tools check response status codes, headers, body content (JSON schema, text patterns), and return validation results (pass/fail) with detailed error messages. Useful for verifying API contracts and detecting unexpected responses during automation.

Provides playwright_screenshot and playwright_save_as_pdf tools that capture page visuals in PNG or PDF format with optional viewport and full-page rendering. The tools accept options for full-page capture, viewport dimensions, clip regions, and quality settings. Screenshots are returned as base64-encoded PNG, and PDFs are returned as binary files. Useful for visual testing, documentation, and evidence collection.

Extracts visible text, HTML structure, and accessibility tree from the current page via playwright_get_visible_text and playwright_get_page_content tools, and captures full-page or viewport screenshots as PNG/PDF via playwright_screenshot and playwright_save_as_pdf. The extraction logic uses Playwright's textContent() and innerHTML() APIs with optional filtering to return only visible, non-hidden elements.

Provides playwright_navigate, playwright_go_back, playwright_go_forward, and playwright_reload tools that control page navigation using Playwright's page.goto(), page.goBack(), page.goForward(), and page.reload() APIs. Each tool accepts URLs, handles redirects and timeouts, and returns navigation status (success, timeout, network error) with optional wait-for-load-state configuration (load, domcontentloaded, networkidle).

Provides 5 HTTP method tools (playwright_api_get, playwright_api_post, playwright_api_put, playwright_api_patch, playwright_api_delete) that create APIRequestContext instances on-demand to execute REST requests. Each tool accepts URL, headers, body, authentication (Bearer token, Basic auth), query parameters, and returns response status, headers, and body (JSON or text) with optional response validation via expect_response and assert_response tools.

Captures browser console messages (log, warn, error, debug) via playwright_console_logs tool using Playwright's page.on('console') event listener. The ConsoleLogsTool registers a message handler that buffers console messages in memory and returns them as structured objects with message type, text content, and optional stack traces. Useful for debugging JavaScript errors and monitoring application behavior during automation.

Provides start_codegen_session, end_codegen_session, get_codegen_session, and clear_codegen_session tools that manage ActionRecorder instances. When a codegen session is active, all browser tool invocations (click, fill, navigate, etc.) are recorded as action objects. When end_codegen_session is called, the PlaywrightGenerator converts recorded actions into executable Playwright test code (JavaScript or TypeScript) that can be saved and run independently.

Implements the Model Context Protocol (MCP) server that exposes 36 tools (27 browser, 5 API, 4 codegen) as MCP resources. The server receives tool invocation requests via STDIO transport, routes them through requestHandler.ts and toolHandler.ts, executes the appropriate tool via the tool's execute(args, context) method, and returns ToolResponse objects with result or error. Each tool is registered with JSON schema describing parameters and return types, enabling MCP clients (Claude Desktop, Cline, Cursor) to discover and invoke tools with type safety.

Provides playwright_wait_for_selector and playwright_wait_for_navigation tools that poll for element visibility or navigation completion using Playwright's waitForSelector() and waitForNavigation() APIs. The tools accept CSS selectors, XPath, or Playwright locators, and timeout values (default 30s), and return success/timeout status. Useful for handling dynamic content loading, AJAX requests, and asynchronous page updates.

Provides playwright_type, playwright_press, playwright_hover, and playwright_drag tools that simulate keyboard and mouse events using Playwright's type(), press(), hover(), and drag() APIs. The tools accept element selectors, keyboard input strings, modifier keys (Shift, Ctrl, Alt, Meta), and drag source/target coordinates. Useful for complex interactions like keyboard shortcuts, form filling with special characters, and drag-and-drop operations.