npm / @playwright/mcp
@playwright/mcp
What changed in @playwright/mcp 0.0, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-15.
44 breaking7 security113 new APIs and options24 behavior and defaults49 tooling84 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@playwright/mcp 0.0321 changes
Breaking changes 44
Source locations in console messages and tool-response console entries now use editor-style line numbers starting at 1.
Exceptions from page and context listeners installed through this tool appear in tool responses and browser_console_messages instead of escaping as unhandled errors.
Snapshots no longer hide content solely because it is inert or outside a modal dialog; click, fill and select still wait for explicitly inert targets to become non-inert.
Profile, executable, storage-state, output and other config paths resolve against the config file's directory, or its target's directory for a symlink; CLI and environment paths remain working-directory-relative.
Unknown device values produce an explicit error, and per-client overrides no longer mutate shared device presets.
Snapshots and accessible names omit unrendered text, including unslotted shadow-host text and text directly inside closed details.
Supplying both text and textGone waits for the first condition to happen instead of waiting for both in sequence.
When combined with a text condition, time is its timeout, capped at 30 seconds, rather than a delay before checking it.
Snapshots exclude inert content and content outside the topmost modal dialog; click and fill actions wait for targets to stop being inert.
With HTTP transport, an idle client's context expires even while another client keeps the shared browser busy.
WebMCP tool calls work with Chromium 155 and later.
The style option accepts point, highlight and title CSS declarations; markers are shown only when styled.
This tool is no longer exposed over MCP, replaced by direct calls to page-registered WebMCP tools.
This tool is no longer exposed over MCP, replaced by page-registered WebMCP tools in the tool list.
The Chromium sandbox is disabled by default on Linux for the bundled Chromium build, which lacks the setuid sandbox helper.
Follows symlinks so a symlink inside the workspace cannot be used to read or write files outside the allowed roots.
Headless browsers launched by the server close after one hour without tool calls; the next tool call launches a new browser. Headed and attached browsers are unaffected unless a timeout is set explicitly.
Returns the original screenshot bytes instead of silently downscaling them to model-specific limits.
The default codegen language is inferred from the environment.
The internal endpoint is no longer registered outside of tests.
Removes support for extension protocol v1.
Removes the stale CLI option.
Snapshots are distilled to reduce noise and token usage.
Snapshot and network output no longer includes data: URL payloads.
Replaces browser_run_code with a name that makes the sandbox-escape implication explicit.
Ignores browser configuration such as channel, headless, and viewport when attaching to the extension.
Merges user-supplied ignoreDefaultArgs with persistent mode defaults instead of replacing them.
Replaces the navigation protocol allowlist with a blocklist for better coverage.
The CLI flag name is restored to --no-sandbox.
Renames --[no-]sandbox for clarity and to avoid ambiguity with other browsers.
Browser profiles are in-memory by default, so every session starts clean with no leftover state.
The shorter -s= flag replaces --session for selecting a session.
The --session flag has been replaced with -s=.
Sessions no longer have a stopped state; they are either running or gone.
Renames --isolated to --in-memory; the browser profile exists only in memory, is not persisted to disk, and starts clean on every run.
Renames the browser installation command to install-browser.
The CLI uses a dedicated persistent profile by default, preserving cookies and other storage state between calls.
The CLI uses a dedicated persistent profile by default, preserving cookies and other storage state between calls.
MCP-recorded videos are now saved under outputDir/videos.
Browser navigation and API requests are limited to http:, https:, about:, and data: URLs; file:// is blocked by default.
File uploads through setInputFiles, file choosers, and MCP file tools are restricted to workspace root directories, or cwd when no roots are configured.
The MCP extension now connects only to MCP servers running on the same machine.
Successfully downloaded static resources are no longer returned by default; pass includeStatic to include them.
The flag is gone; use --proxy as a safer alternative or rely upon underlying OS policies.
Security 7
Configure named query and fragment parameters to have their runtime values replaced with
<redacted>in tool responses.Validates Host and Origin headers on CDP relay WebSocket upgrades.
Escapes user input in generated code.
The default browser now enables the chromium sandbox.
Secrets are redacted in console log artifacts.
Adds path-traversal checks to static file serving routes.
Validates user-provided regex patterns in MCP tools.
New APIs and options 113
With --extension, leaves the connected tab inactive and its window unfocused, and opens client tabs in the background.
With an extension connection, leaves the connected tab inactive and its window unfocused, and opens client tabs in the background.
When enabled, restricts locators to visible elements in element-tool targets and browser_run_code_unsafe; off by default.
With --extension, keeps the selected tab and client-opened tabs in their existing groups, if any.
Setting this environment variable to 1 leaves the connected tab inactive and its window unfocused, and opens client tabs in the background.
Setting this environment variable to 1 keeps controlled tabs in their existing groups, if any.
Setting this to false with an extension connection keeps controlled tabs in their existing groups, if any.
Optional domain and path filters let cookie deletion leave same-name cookies on other domains and paths untouched.
A positive integer maxResults limits returned matches to the first matching items with context and reports the total match count.
Set all to true to include retained request history from earlier navigations, up to 200 requests.
The new-tab action accepts an isolatedContext name; tabs with the same name share a context, while different names stay isolated.
Skip the roots/list request and use the server's current working directory as the workspace root.
Element tools accept JavaScript, Python, Java, and C# locators alongside snapshot refs and CSS selectors.
browser_find takes filename to save matches to a file instead of returning them in the response.
The new tool emulates colorScheme, reducedMotion, forcedColors, contrast and media type on the fly; omitted parameters remain unchanged and null clears an override.
The cursor option renders an animated mouse cursor that travels to each action point and stays visible between actions.
The tool takes fps, allowing recordings such as fps: 60 instead of the default 25.
Set this option to absolute to return absolute paths for snapshots, screenshots, console logs and downloads.
Set filePaths to absolute to return absolute paths for snapshots, screenshots, console logs and downloads.
Pass this flag to opt out of WebMCP tools.
Set this environment variable to absolute to return absolute paths for snapshots, screenshots, console logs and downloads.
Set this environment variable to false to opt out of WebMCP tools.
Clients receive this notification when the page's WebMCP tool list changes.
Set webmcp to false in configuration to opt out of WebMCP tools.
Calls the tools a page registers through the WebMCP API, letting the page do the work instead of driving its UI.
Lists the tools a page registers through the WebMCP API, letting the page do the work instead of driving its UI.
Changes the idle timeout; setting it to 0 disables the timeout.
Accepts
only, which returns image parts alone for a response carrying an image, without the text part.Selects which Chrome profile to connect to in extension mode when the extension is installed in several profiles.
Starts recording actions the user performs manually in the browser and returns them as Playwright code; opt in via --caps=devtools.
Stops recording actions the user performs manually in the browser and returns them as Playwright code; opt in via --caps=devtools.
Adds a type option for png, jpeg, or webp screenshots; when unset, the format is inferred from the filename extension.
Launches the Chrome profile that has the extension installed.
Enables bounding boxes in snapshots globally; previously this was only available per command.
Controls how long to wait after each action for triggered work, such as navigations and requests, to settle; defaults to 500ms.
Configures how long to wait after each action for triggered work, such as navigations and requests, to settle; defaults to 500ms.
Searches the current page's accessibility snapshot for text or a regular expression and returns matching nodes with surrounding context.
Adds a CLI option to emulate mobile devices.
Adds a CLI flag to emulate mobile devices.
Waits for the next pause or context closure.
The scale option lets you choose CSS-pixel screenshots or higher-resolution device-pixel screenshots.
The heartbeat ping timeout is now configurable.
Adds a tool to hide action annotations on recorded video.
Adds a tool to overlay action annotations on recorded video.
Caps tool response size and evicts oversized output from disk after the response.
Accepts a ConnectOptions object instead of only a URL string.
Supports setting headers for the remote browser endpoint.
Accepts a filename option to write output to a file.
Fetches full details or a single part of a request using its index from browser_network_requests.
Returns a numbered list of requests; use browser_network_request with an index to fetch full details or a single part.
Accepts a filename option to write output to a file.
Exposes Locator.drop as an MCP tool for completing drag-and-drop operations onto a target.
Adds the responseBody option; binary response bodies are rendered as a placeholder using mime-type detection.
Adds the responseHeaders option to browser_network_requests.
Adds a button option for more precise mouse interaction control.
Adds a clickCount option for more precise mouse interaction control.
Adds a delay option for more precise mouse interaction control.
Responses can optionally include the body.
Responses can optionally include headers.
Adds filtering support to the network requests tool.
Adds a tool to toggle network offline mode for testing connectivity scenarios.
Adds a tool to add a chapter marker to a video recording with a full-screen chapter card and blurred backdrop.
Adds an mcpName package field for MCP Registry ownership verification.
Tools now accept plain CSS and text selectors in addition to aria-ref handles.
Use --persistent to opt into a persistent profile instead of the default in-memory profile.
Close all browsers with the new close-all command.
Forcefully kill all browser processes with the new kill-all command.
Use --profile=<path> to specify a custom profile directory.
Deletes a browser cookie by name.
Gets a LocalStorage value by key.
Saves browser state to a file, enabling login sessions and reproducible browser state across runs.
Select a non-Chromium browser, with Firefox shown as an available choice.
The devtools capability makes on-demand video recording available in Playwright MCP.
Use an isolated, ephemeral browser context with the CLI.
Configure a persistent session, including options such as headed mode and a configuration file.
Use the extension option to snapshot a shared browser tab through the Playwright Chrome extension.
The mcp binary is released and scoped to Playwright for use in the NPX world.
The CLI supports environment configuration, including selecting a session with PLAYWRIGHT_CLI_SESSION.
Pass --headed to open to see the browser; the CLI is headless by default.
Session commands let developers list, stop, and delete browser sessions and their profile data.
Check a checkbox or radio button.
Close the page.
Perform a double click on a web page.
Accept a dialog, optionally providing a prompt value.
Dismiss a dialog.
Go back to the previous page.
Hover over an element on the page.
Release a key on the keyboard.
Press the mouse button down.
Release the mouse button.
Open a URL in the browser; pass --headed to display the browser.
Press a key on the keyboard.
Set this environment variable to run a coding agent with a selected CLI session.
List all sessions.
Use --session to address a specific browser instance with a separate profile.
Stop all sessions.
Close a browser tab by index.
Create a new tab, optionally opening a URL.
Stop trace recording.
Type text into an editable element.
Added a configuration option to control CDP connection timeouts; the default is 30s, and 0 disables the timeout.
Adds an opt-out flag that allows access to files outside workspace roots and navigation and requests to file:// URLs.
Adds a configuration option to opt out of file access and protocol restrictions.
Accepts an optional filename parameter to save the snapshot to disk and show a link in the Files section, avoiding large inline snapshots and smaller MCP payloads.
Accepts a level parameter to include console messages up to the given severity.
Configures the console severity level included in replies; defaults to info.
Configures snapshot output mode; defaults to incremental.
The --allow-origins flag is brought back; point it only at trusted origins.
Run batches of Playwright APIs in one command, speeding up repetitive operations and saving context tokens.
Point to a TypeScript file evaluated on the Playwright page object to run setup code.
Point to a JavaScript file added as an initialization script and evaluated in every page before its scripts.
Load cookies and local storage from a file into an isolated browser context.
Start with a user data directory to persist all browser data between sessions.
Behavior and default changes 24
Its description no longer rules out acting on a screenshot; with --caps=vision, it points to coordinate-based mouse tools for elements the snapshot does not expose.
In Chrome and Edge's new headless mode, the window is sized to fit the viewport below the tab strip and toolbar, preventing browser_start_video from cropping the page bottom.
Added request header names match case-insensitively; mocked responses include custom headers, and request-header changes preserve origin filters and other routes.
HTTP clients can connect through localhost, 127.0.0.1, or [::1] regardless of the bind address; other hosts still require --allowed-hosts.
Credentials embedded in the proxy URL are passed to the browser as proxy authentication settings.
Reports how many WebMCP tools are available on a page.
Reconnects to the browser after a disconnect.
Now surfaces non-2xx navigation status codes.
Assigns caps as an array for the legacy --vision flag.
Supports the
moz-firefoxBiDi channel.Browser-level CDP commands are forwarded in extension mode.
Shared browser launches are serialized in isolated mode.
Abort signals are propagated to stop test execution.
When
filenameis explicitly provided, the response skips the base64 image.The browser extension now supports managing multiple tabs when used with this flag.
The session now auto-recovers if the remote browser disconnects mid-session.
The extension channel is now resolved from CLI flags and environment variables.
The extension executablePath is now resolved from CLI flags and environment variables.
Accepts plain expressions in addition to function bodies.
Connected tabs are grouped into a green Playwright tab group.
Each workspace gets its own daemon process, preventing cross-project interference and enabling direct daemon startup for faster, more reliable operation.
Now takes a function and supports return statements.
pageState supports diffs, collapsing unchanged subtrees to reduce noise and payload size.
Limits on rendered image sizes prevent resource overuse.
Tooling 49
Code generation supports python, java, and csharp in addition to typescript.
List all sessions with the new list command.
Clears browser cookies.
Gets a browser cookie by name.
Lists browser cookies for storage inspection and debugging.
Sets a browser cookie, with an optional domain.
Adds a command to install SKILLS locally.
Clears LocalStorage.
Lists LocalStorage entries for browser storage inspection.
Sets a LocalStorage value.
Adds CLI-based request mocking by URL pattern, including custom responses, headers, request mutations, and blocking.
Lists active network routes.
Enables advanced request handling through raw Playwright routing, including conditional responses, response mutation, and simulated network failures.
Clears SessionStorage.
Lists SessionStorage entries for browser storage inspection.
Sets a SessionStorage value.
Loads browser state from a file for reproducible auth flows and stateful automation.
Removes a matching route or all active routes.
A Playwright CLI executable is available for running browser commands such as open and snapshot.
Start on-demand video recording from the CLI; pair with video-stop to save a recording.
Stop on-demand video recording from the CLI and produce a video file.
The CLI supports browsers other than Chrome.
The CLI supports a config file named playwright-cli.json.
Adds an official, token-efficient CLI mode with commands for browser interaction, navigation, keyboard and mouse input, screenshots, tabs, and DevTools.
Perform a click on a web page.
List console messages, optionally filtered by minimum level.
Perform drag and drop between two elements.
Evaluate a JavaScript expression on a page or element.
Fill text into an editable element.
Go forward to the next page.
Press a key down on the keyboard.
Move the mouse to a given position.
Scroll the mouse wheel.
List network requests since the page loaded.
Save the page as a PDF.
Reload the current page.
Resize the browser window.
Run a Playwright code snippet.
Save a screenshot of the current page or an element.
Select an option in a dropdown.
Delete session data along with its profiles.
Stop a named session.
Capture a page snapshot to obtain an element reference.
List all tabs.
Select a browser tab by index.
Start trace recording.
Uncheck a checkbox or radio button.
Upload one or multiple files.
A token-efficient CLI mode for Playwright is available for coding agents and interactive use.
Fixes and other changes 84
Returns readable representations of BigInt, NaN, Infinity, undefined and circular objects instead of losing values or failing JSON serialization; JSON-compatible results keep their format.
In browsers launched by the server, HTTP URLs stay on HTTP instead of Chrome automatically upgrading them to HTTPS.
Snapshots retain identifying names on containers and table headers when the naming text also appears among their children.
Full-page screenshots now work on standalone SVG documents instead of waiting for a nonexistent HTML body.
Channel-based connections now use the WebSocket path advertised in DevToolsActivePort.
Extension profile lookup now respects this Linux config directory environment variable.
Tool responses report when a page closes before its snapshot is captured and explain when Chrome detached the debugger because of an unsupported frame.
Element tools recognize form-associated custom elements through native label associations, including for attributes and nested labels; accessible names use associated labels too.
Extension connections no longer overwrite the existing browser's font settings, avoiding unexpected changes to page rendering.
Snapshots and role locators include selected-option text when a custom listbox uses a mixed-case aria-selected value such as TRUE.
Tool calls no longer hang during settling delays when page timers are throttled, paused or otherwise unable to run.
Names containing ~, .inf, and .nan remain strings rather than being parsed as null or special floating-point values.
Snapshots and role locators recognize tab- or newline-separated label IDs and labels assigned through ariaLabelledByElements, while retaining attribute-based labels in older browsers.
Reported message counts are now consistent with the existing all option.
Domain and path filtering now respects boundaries instead of matching unrelated names such as notexample.com or /apiary.
An explicit domain is requested when the current page has no hostname.
A dialog opened during history navigation is reported instead of causing a timeout.
Scheme-less hosts with ports are handled, and loopback addresses use HTTP.
Request indexes remain stable across navigations, so earlier requests can still be addressed.
Windows drive-letter colons are no longer mistaken for the line-number separator.
Route handler exceptions are reported once and verbatim, without wrapping non-Error values in another error.
Snapshots retain an iframe's contents when the iframe element also contains fallback text.
Snapshots and role locators recognize mixed-case role and ARIA state values, including checked, pressed, and expanded states.
Reports a dialog opened during page load instead of timing out.
The server no longer crashes when the browser is closed during a download.
Reports when time is capped at 30 seconds.
Reaps orphaned browser processes.
Accessible names that look like regexes are quoted.
Tools no longer stay bound to a stale tab or frame.
A failed upload, such as for a missing file, reports the error and keeps the file chooser open so it can be retried.
The tool returns an error for a header that is not in Name: Value form instead of setting a header named an empty string.
For origins with an active service worker, the tool no longer runs the site's own scripts or fails when they redirect.
Returns an error when the browser context is shared instead of breaking the calling client's session.
Resolves relative paths against the workspace root.
With shared browser context enabled, keeps each client's recording separate instead of delivering one client's recorded actions to another.
In extension mode, a connection that never completes now fails after 30 seconds with a hint instead of hanging the tool call.
Drops the cached browser backend after closing a shared browser context, so subsequent tool calls from the same client no longer fail.
When connected to a remote endpoint, reports the browser actually running remotely instead of the configured one.
The setting from the config file is no longer clobbered.
The heartbeat is not run for HTTP clients that have not opened an event stream.
Orphaned browser preferences entries are no longer treated as an installed extension.
The user data directory setting is honored in extension mode.
Aria snapshot capture is skipped when the response discards it.
Surfaces the missing executable path when a browser isn't installed.
Clears the dialog modal state when a dialog is closed out of band.
Detects downloads through the download event instead of inferring them from net::ERR_ABORTED navigation errors.
Malformed JSON config is reported instead of silently falling back to INI parsing.
No longer crashes the response when navigation closes the last tab, such as on privileged pages.
CDP connections always pass
noDefaults, preventing unwanted default context options when attaching.Additional tab videos now preserve the configured output directory.
Page initialization is awaited before a screenshot taken immediately after opening.
Checks tracing state before stopping.
Passes the action timeout to waitFor calls.
A failed network request is listed only once.
Reports a missing
ffmpegdistinctly from a missing browser.Reports invalid tool arguments instead of failing opaquely.
The system now recovers from a page renderer crash.
The browser channel is now propagated when using the --extension path.
Dashboard annotate-screenshot now handles a null viewport.
Playwright MCP is now published to the official MCP Registry on each release, making it available through that registry.
Surfaces unhandled rejections instead of crashing the server.
Detects the installed extension in non-default Chrome profiles.
Disables the CDP timeout for extension connections so long handshakes do not fail.
Ensures --proxy-server overrides the proxy set in the config file.
Fixes file path validation in the storage state tool.
Fixes empty cdpHeaders from the environment overriding values in the config file.
Fixes executable location resolution in the browser extension.
Fixes inactivity timers not being armed for pending tabs.
Fixes the fs-based lock file not being respected for Chromium family browsers.
Fixes parsing header values that contain colons.
Fixes malformed Unicode characters in MCP tool responses.
Fixes persistent contexts incorrectly using per-session isolation.
Fixes non-deterministic right-click behavior caused by contextmenu and mouseup ordering.
Fixes console entries being printed when snapshot mode is set to none.
Fixes toWellFormed compatibility with Node.js 18.
Fixes verify tools not working inside iframes.
The Google Chrome extension is now available in the Chrome Web Store.
Fixes the CLI on Windows.
Improved messaging when the browser profile is already in use, including Windows-specific exit cases.
Improved diagnostics for missing system dependencies and suggested running playwright install-deps.
Fixed an issue where empty snapshots were sometimes written into .md files.
Fixed persistence of saveVideo in configs.
Fixed a failure affecting WSL clients connecting to a Windows server.
MCP suggests using relative paths for portability.