Playwright MCP Server

A minimal, robust Playwright MCP (Model Context Protocol) server that exposes core browser automation capabilities via a simple API.

Features

• Browser Context Management: Persistent browser context (headless or headed, configurable)

• Multi-Page Support: Handle multiple tabs/windows, switch between pages, manage popups

• Navigation: Open URLs, reload, go back/forward

• DOM Interaction: Click, type, fill, select, hover, scroll using Playwright selectors

• Element Discovery: Query elements using CSS, XPath, role, text, and other Playwright locators

• Snapshotting: Get HTML, accessibility snapshots, screenshots, and PDFs

• Token-Aware Outputs: Configurable caps keep element queries and accessibility snapshots within safe sizes for LLM consumption

• Overflow Artifacts: Large responses are trimmed automatically, auto-cleaned after ~2 hours by default, and include previews plus file references you can reopen via the artifact reader tools

• Binary-Friendly Defaults: Screenshots, PDFs, and other large blobs are stored as artifacts with metadata previews so LLMs stay in control of context size

• Script Evaluation: Run JavaScript in the page context

• Network Monitoring: Capture and analyze all network requests and responses

• Network Interception: Block, modify, or mock network requests

• Cookie Management: Get, set, and clear browser cookies

• Storage Access: Manage localStorage and sessionStorage data

• Headers & User Agent: Customize request headers and browser identity

• Raw Output: All outputs are raw Playwright results with no post-processing

Installation

Quick Install from GitHub

For Development

Usage

Running the Server

After installation, you can use it from anywhere:

Command Line Usage

Integration with Claude Desktop

Add to your claude_desktop_config.json:

Testing with MCP Inspector

Response Budgeting & Artifacts

High-volume tools (evaluate, get_accessibility_snapshot, get_network_requests, get_network_responses, get_html, etc.) honor a shared response budget. When the serialized payload would exceed --max-response-chars:

• The inline result is trimmed to fit the budget and marked with truncated: true.

• A compact preview (default 400 chars) snapshots what was retained.

• The full payload is written to the artifact directory (default tmp/playwright_mcp) and returned as overflow_path plus the original size in overflow_characters.

• Use the read_artifact tool (or open the file locally) to retrieve the saved payload. Artifacts that are binary fall back to base64 when read.

• Artifacts are auto-pruned—by default anything older than two hours is deleted and the directory is capped at 200 files (--artifact-max-age-seconds, --artifact-max-files).

Binary-heavy tools (screenshot, pdf, get_response_body for non-text payloads) now default to artifact responses. They return metadata (size, hash, preview) plus artifact_path. Pass inline=True when you truly need the full base64 inline.

When you need more than the inline preview, use read_artifact_chunk to stream binary/text artifacts in manageable slices (default chunk size is configurable via --artifact-chunk-size).

Tweak the caps per run with --max-response-chars, --preview-chars, and --artifact-dir or override per-call limits where a tool exposes them.

API Reference

Tools

Navigation & Page Control

• navigate(url: str) - Navigate to a URL

• reload() - Reload the current page

• go_back() - Go back in history

• go_forward() - Go forward in history

• get_current_url() - Get current page URL with parsed components and query parameters

• wait_for_url(url_pattern: str, timeout: int) - Wait for URL to match pattern

• wait_for_load_state(state: str, timeout: int) - Wait for page load states (domcontentloaded, load, networkidle)

• set_viewport_size(width: int, height: int) - Set viewport dimensions

Multi-Page Management (Tabs/Windows)

• list_pages() - List all open browser pages/tabs with IDs, URLs, and titles

• switch_page(page_id: str) - Switch to a different page/tab by its ID

• close_page(page_id: str) - Close a specific page/tab (cannot close last one)

• wait_for_popup(timeout: int) - Wait for and capture a new popup/tab

• switch_to_latest_page() - Switch to the most recently opened page

Element Interaction

• click(selector: str) - Click an element

• type_text(selector: str, text: str) - Type text into an element

• fill(selector: str, value: str) - Fill an input field

• clear_text(selector: str) - Clear input field text

• select_option(selector: str, value: str) - Select an option

• hover(selector: str) - Hover over an element

• scroll(selector: str, x: int, y: int) - Scroll element

• press_key(key: str) - Press keyboard key

Form Handling

• check_checkbox(selector: str) - Check a checkbox

• uncheck_checkbox(selector: str) - Uncheck a checkbox

• upload_file(selector: str, file_path: str) - Upload file to input

Element Discovery & Validation

• query_selector(selector: str, max_text_length: int | None = None) - Query for single element (optional per-call text cap override)

• query_selector_all(selector: str, max_elements: int | None = None, max_text_length: int | None = None) - Query for all matching elements (optional per-call overrides)

• query_selector_meta(selector: str, preview_length: int = 200, max_elements: int | None = None) - Quick metadata preview (tag, role, short text, key attributes)

• Element query tools obey global caps, accept per-call overrides, and return truncated / returned_count metadata when results are clipped.

• is_visible(selector: str) - Check if element is visible

• is_enabled(selector: str) - Check if element is enabled

• wait_for_element(selector: str, timeout: int) - Wait for element to appear

• get_element_bounding_box(selector: str) - Get element position and size

• get_element_attributes(selector: str) - Get all element attributes

• get_computed_style(selector: str, property: str) - Get CSS computed style

Script Evaluation & Diagnostics

• evaluate(script: str) - Execute JavaScript in page context (results respect the shared response budget and emit overflow metadata as needed)

Network Monitoring & Overflow Retrieval

• get_network_requests(url_pattern: str | None = None) - Inspect captured requests; large result sets spill to artifacts with previews

• get_network_responses(url_pattern: str | None = None) - Inspect captured responses with the same budgeting behaviour

• read_artifact(path: str) - Load the first chunk of an overflow artifact referenced in a previous response (returns text or base64 content)

• read_artifact_chunk(path: str, offset: int = 0, limit: int | None = None) - Stream additional artifact data in bounded chunks

• get_response_body(url_pattern: str) - Fetch the latest matching response body; text is budgeted inline, binary payloads are saved to artifacts automatically

Content & Snapshots

• get_html() - Get page HTML

• get_accessibility_snapshot(interesting_only: bool = True, root_selector: str | None = None, max_nodes: int | None = None) - Get accessibility tree with optional filters and per-call node caps

• Accessibility snapshots are pruned to the configured node budget, accept per-call overrides, and include truncated, max_nodes, and node_count metadata.

• screenshot(selector: str | None = None, full_page: bool = False, inline: bool = False) - Capture page or element; stores the PNG as an artifact with metadata previews by default

• pdf(inline: bool = False) - Generate a PDF and return artifact metadata unless inline mode is explicitly requested

JavaScript & Debugging

• evaluate(script: str) - Execute JavaScript in page context

• wait_for_network_idle(timeout: int) - Wait for network activity to settle

• get_page_errors() - Get JavaScript errors from page

• get_console_logs() - Get console output from page

Network Monitoring & Interception

• get_network_requests(url_pattern: str) - Retrieve captured network requests with filtering

• get_network_responses(url_pattern: str) - Retrieve captured network responses with filtering

• clear_network_logs() - Clear all captured network request/response logs

• intercept_route(url_pattern: str, action: str, ...) - Intercept and handle network requests

• unroute_all() - Remove all route interceptors

• wait_for_response(url_pattern: str, timeout: int) - Wait for specific network responses

• get_response_body(url_pattern: str) - Extract response body content from network calls

Cookie Management

• get_cookies(urls: List[str]) - Retrieve browser cookies with optional URL filtering

• add_cookies(cookies: List[Dict]) - Add cookies to browser context

• clear_cookies(name: str, domain: str) - Clear cookies with optional filtering

Storage Management

• get_local_storage(origin: str) - Access localStorage data

• set_local_storage(key: str, value: str) - Set localStorage items

• get_session_storage() - Access sessionStorage data

• set_session_storage(key: str, value: str) - Set sessionStorage items

• clear_storage(storage_type: str) - Clear localStorage and/or sessionStorage

Request Headers & Identity

• set_extra_headers(headers: Dict) - Add custom HTTP headers to all requests

• set_user_agent(user_agent: str) - Change browser User-Agent string

Examples

Handling Multiple Pages/Tabs

The server automatically tracks all browser pages/tabs:

All existing tools automatically work on the currently active page. When you switch pages, subsequent operations apply to the new active page.

Configuration

The server accepts the following configuration options:

• --headed / --headless - Run browser in headed or headless mode

• --browser - Browser type (chromium, firefox, webkit)

• --channel - Browser channel (chrome, chrome-beta, msedge, etc.) for real browsers

• --user-data-dir - Path to browser profile directory for persistent context

• --port - Port for HTTP transport

• --timeout - Default timeout for operations (ms)

• --max-elements - Maximum number of DOM nodes returned by query tools (default: 20)

• --max-element-text-length - Maximum characters returned for element text and attribute values (default: 2000)

• --max-accessibility-nodes - Maximum accessibility tree nodes returned by get_accessibility_snapshot (default: 500)

• --max-response-chars - Maximum serialized characters returned inline before results spill to artifact files (default: 4000)

• --preview-chars - Maximum characters included in inline previews when truncation occurs (default: 400)

• --artifact-dir - Directory where overflow artifacts are written (default: ./tmp/playwright_mcp)

• --artifact-max-age-seconds - Maximum age before artifacts are purged (default: 7200 seconds)

• --artifact-max-files - Maximum number of artifact files kept in the directory (default: 200)

• --artifact-chunk-size - Default number of bytes returned per read_artifact_chunk call (default: 4096)

All caps accept 0 or negative values to disable truncation entirely. When truncation occurs, tool responses include truncated flags and metadata so clients can optionally re-issue a narrower request.

Real Chrome vs Bundled Chromium

By default, Playwright uses bundled Chromium. For web scraping that requires real Chrome features:

Use to use your installed Google Chrome:

• Access to all Chrome features and codecs

• Better compatibility with some websites

• Chrome-specific behaviors

Use to access your real profile:

• All your cookies and login sessions

• Browser extensions (AdBlock, etc.)

• Browsing history and autofill data

• Bookmarks and saved passwords

Example for macOS:

Example for Linux:

Development

License

MIT