Skip to main content

Playwright MCP server guide

Overview​

The official Playwright MCP server provides browser automation capabilities using Playwright. This server enables AI agents to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models.

Key features include:

  • Fast and lightweight: Uses Playwright's accessibility tree instead of pixel-based input
  • LLM-friendly: Operates purely on structured data without requiring vision models
  • Deterministic tool application: Avoids ambiguity common with screenshot-based approaches
  • Multi-browser support: Works with Chrome, Firefox, Safari (WebKit), and Edge
  • Tab management: Create, switch between, and manage multiple browser tabs
  • Persistent sessions: Maintains login state and browser data between interactions

Metadata​

Expand to view the MCP server's metadata
Server metadata
Name: io.github.stacklok/playwright
Type: container
Description: Provides browser automation capabilities using Playwright
Tier: Official
Status: Active
Transport: stdio
Image: mcr.microsoft.com/playwright/mcp:v0.0.70
Has Provenance: No

Permissions:
  Network:
    Insecure Allow All: true
    Allow Port: 443
Repository URL: https://github.com/microsoft/playwright-mcp
Popularity: 28552 stars
Last Updated: 2026-04-27T16:41:23Z

Tools:
  - browser_click
  - browser_close
  - browser_console_messages
  - browser_drag
  - browser_evaluate
  - browser_file_upload
  - browser_fill_form
  - browser_handle_dialog
  - browser_hover
  - browser_navigate
  - browser_navigate_back
  - browser_network_requests
  - browser_press_key
  - browser_resize
  - browser_run_code
  - browser_select_option
  - browser_snapshot
  - browser_tabs
  - browser_take_screenshot
  - browser_type
  - browser_wait_for

Environment Variables:
  - PLAYWRIGHT_MCP_ALLOWED_HOSTS: Comma-separated list of hosts this server is allowed to serve from. Defaults to the host the server is bound to. Pass '*' to disable the host check.
  - PLAYWRIGHT_MCP_ALLOWED_ORIGINS: Semicolon-separated list of trusted origins to allow the browser to request. Default is to allow all.
  - PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS: Allow access to files outside of the workspace roots, including unrestricted access to file:// URLs.
  - PLAYWRIGHT_MCP_BLOCKED_ORIGINS: Semicolon-separated list of origins to block the browser from requesting. Evaluated before the allowlist.
  - PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS: Block service workers.
  - PLAYWRIGHT_MCP_BROWSER: Browser or chrome channel to use. Possible values: chrome, firefox, webkit, msedge.
  - PLAYWRIGHT_MCP_CAPS: Comma-separated list of additional capabilities to enable. Possible values: vision, pdf, devtools.
  - PLAYWRIGHT_MCP_CDP_ENDPOINT: CDP endpoint to connect to.
  - PLAYWRIGHT_MCP_CDP_HEADER: CDP headers to send with the connect request. Multiple can be specified.
  - PLAYWRIGHT_MCP_CDP_TIMEOUT: Timeout in milliseconds for connecting to the CDP endpoint. Defaults to 30000.
  - PLAYWRIGHT_MCP_CODEGEN: Language to use for code generation. Possible values: typescript, none. Defaults to typescript.
  - PLAYWRIGHT_MCP_CONFIG: Path to the configuration file.
  - PLAYWRIGHT_MCP_CONSOLE_LEVEL: Level of console messages to return: error, warning, info, debug. Each level includes messages of more severe levels.
  - PLAYWRIGHT_MCP_DEVICE: Device to emulate, for example 'iPhone 15'.
  - PLAYWRIGHT_MCP_ENDPOINT: Bound browser endpoint to connect to.
  - PLAYWRIGHT_MCP_EXECUTABLE_PATH: Path to the browser executable.
  - PLAYWRIGHT_MCP_EXTENSION: Connect to a running browser instance (Edge/Chrome only). Requires the Playwright Extension to be installed.
  - PLAYWRIGHT_MCP_GRANT_PERMISSIONS: List of permissions to grant to the browser context, for example 'geolocation', 'clipboard-read', 'clipboard-write'.
  - PLAYWRIGHT_MCP_HEADLESS: Run browser in headless mode. Headed by default.
  - PLAYWRIGHT_MCP_HOST: Host to bind the server to. Use 0.0.0.0 to bind to all interfaces. Defaults to localhost.
  - PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS: Ignore HTTPS errors.
  - PLAYWRIGHT_MCP_IMAGE_RESPONSES: Whether to send image responses to the client. Possible values: allow, omit. Defaults to allow.
  - PLAYWRIGHT_MCP_INIT_PAGE: Path to a TypeScript file to evaluate on the Playwright page object.
  - PLAYWRIGHT_MCP_INIT_SCRIPT: Path to a JavaScript file to add as an initialization script. Evaluated on every page before any of the page's scripts. Can be specified multiple times.
  - PLAYWRIGHT_MCP_ISOLATED: Keep the browser profile in memory; do not save it to disk.
  - PLAYWRIGHT_MCP_NO_SANDBOX: Disable the sandbox for all process types that are normally sandboxed.
  - PLAYWRIGHT_MCP_OUTPUT_DIR: Path to the directory for output files.
  - PLAYWRIGHT_MCP_OUTPUT_MODE: Whether to save snapshots, console messages, and network logs to a file or to standard output. Possible values: file, stdout. Defaults to stdout.
  - PLAYWRIGHT_MCP_PORT: Port to listen on for SSE transport.
  - PLAYWRIGHT_MCP_PROXY_BYPASS: Comma-separated domains to bypass the proxy, for example '.com,chromium.org,.domain.com'.
  - PLAYWRIGHT_MCP_PROXY_SERVER: Proxy server, for example 'http://myproxy:3128' or 'socks5://myproxy:8080'.
  - PLAYWRIGHT_MCP_SANDBOX: Enable the sandbox for all process types that are normally not sandboxed.
  - PLAYWRIGHT_MCP_SAVE_SESSION: Whether to save the Playwright MCP session into the output directory.
  - PLAYWRIGHT_MCP_SECRETS: Path to a file containing secrets in the dotenv format.
  - PLAYWRIGHT_MCP_SHARED_BROWSER_CONTEXT: Reuse the same browser context between all connected HTTP clients.
  - PLAYWRIGHT_MCP_SNAPSHOT_MODE: Mode to use when taking snapshots for responses. Possible values: full, none. Defaults to full.
  - PLAYWRIGHT_MCP_STORAGE_STATE: Path to the storage state file for isolated sessions.
  - PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE: Attribute to use for test ids. Defaults to data-testid.
  - PLAYWRIGHT_MCP_TIMEOUT_ACTION: Action timeout in milliseconds. Defaults to 5000.
  - PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION: Navigation timeout in milliseconds. Defaults to 60000.
  - PLAYWRIGHT_MCP_USER_AGENT: User agent string.
  - PLAYWRIGHT_MCP_USER_DATA_DIR: Path to the user data directory. If not specified, a temporary directory will be created.
  - PLAYWRIGHT_MCP_VIEWPORT_SIZE: Browser viewport size in pixels, for example '1280x720'.

Tags:
  playwright, automation, browser, navigate, testing, web, accessibility

Example Command:
  thv run playwright

Usage​

The Playwright MCP server supports numerous command-line arguments to customize its behavior. Common options include:

  • Custom viewport: Set --viewport-size to specify browser dimensions (e.g., 1920,1080)
  • Device emulation: Use --device to emulate mobile devices (e.g., "iPhone 15")
  • Network isolation: Configure --allowed-origins and --blocked-origins to control which websites the browser can access
  • Output directory: Specify --output-dir to save screenshots, PDFs, and other files to a custom location; mount a host directory for persistence (see examples below)

Refer to the Playwright MCP server documentation for the full list of configuration options and their descriptions.

Limitations

The containerized version of Playwright only supports the Chromium browser in headless mode.

Select the playwright MCP server in the ToolHive registry. The server runs with default settings that work for most use cases.

To customize the server's behavior, add command-line arguments in the Command arguments section.

To save browser output files like screenshots and traces, mount a host directory in the Storage volumes section and add the --output-dir <container-path> command argument as shown in the screenshot below.

Playwright MCP server UIPlaywright MCP server UI

Sample prompts​

Here are some sample prompts you can use to interact with the Playwright MCP server:

  • "Navigate to https://toolhive.dev and take a screenshot of the homepage"
  • "Go to the login page, fill in the username field with 'testuser' and password field with 'password123', then click the login button"
  • "Open https://news.ycombinator.com and get the titles of the top 5 stories"
  • "Navigate to a form on https://httpbin.org/forms/post, fill it out with sample data, and submit it"
  • "Go to https://github.com/microsoft/playwright and check if there are any console errors on the page"
  • "Take a full-page screenshot of https://example.com and save it as 'homepage.png'"
  • "Navigate to an e-commerce site, search for 'laptop', and capture information about the first product"
  • "Open multiple tabs, navigate to different websites in each, and then switch between them"
  • Use accessibility-first interactions: The server works best when you describe elements by their accessible names, labels, or text content rather than visual characteristics.
  • Leverage browser profiles: For workflows requiring authentication, use persistent profiles or storage state files to maintain login sessions.
  • Enable network restrictions: Use --allowed-origins and --blocked-origins to limit which domains the browser can access, especially in production environments.
  • Monitor resource usage: Browser automation can be resource-intensive; consider using headless mode and limiting concurrent sessions.
  • Handle dynamic content: Use the browser_wait_for tool when dealing with content that loads asynchronously.
  • Organize output files: Specify a custom output directory to keep screenshots, PDFs, and traces organized.
  • Test responsively: Use device emulation to test how web applications behave on different screen sizes and devices.