How do I install Playwright MCP?

Run `npx -y @playwright/mcp@latest` from an MCP client that supports local servers. The catalog requires Node.js, and Playwright downloads its browser binaries when the runtime needs them.

How do I use Playwright MCP with Claude Code?

Add `npx -y @playwright/mcp@latest` as a local MCP server in Claude Code. After it connects, Claude Code can call the browser functions exposed by that process.

What is the Playwright MCP Chrome extension used for?

The extension lets the server attach to an existing Chrome or Edge tab. That is the path to a browser session that is already signed in instead of a new isolated profile.

Can Playwright MCP run in Docker?

Yes. The official Docker setup runs the server with a headless Chromium browser. Docker separates the process and browser files, but it does not make browser actions safe by itself.

How do I run Playwright MCP headless?

Start the server with the `--headless` option. The Docker deployment uses headless Chromium; a local setup can use the same option when no visible browser window is wanted.

How do I use Playwright MCP in Cursor?

Add the local Playwright command to Cursor's MCP settings or `.cursor/mcp.json`, then enable the server. Cursor Agent can use it after the MCP connection starts.

How does Playwright MCP handle authentication?

A fresh browser profile has no login state. To keep a session, use a persistent profile, provide saved storage state, or connect through the extension to a browser tab that is already signed in.

Playwright | Longwave

What it does

Playwright gives an agent access to a real browser. It can open a website, use its controls, read what the page exposes, and capture what happened.

Open pages and move through a website.
Click buttons, fill forms, choose options, and upload files.
Read the page structure instead of guessing from a screenshot.
Capture screenshots and inspect browser messages and network requests.
Work across multiple browser tabs.

Available functions

browser_click Perform click on a web page

Arguments

button: string Button to click, defaults to left Allowed values: left, right, middle
doubleClick: boolean Whether to perform a double click instead of a single click
element: string Human-readable element description used to obtain permission to interact with the element
modifiers: array Modifier keys to press
target required: string Exact target element reference from the page snapshot, or a unique element selector

browser_close Close the page

browser_console_messages Returns all console messages

Arguments

all: boolean Return all console messages since the beginning of the session, not just since the last navigation. Defaults to false.
filename: string Filename to save the console messages to. If not provided, messages are returned as text.
level required: string Level of the console messages to return. Each level includes the messages of more severe levels. Defaults to "info". Allowed values: error, warning, info, debug Default: info

browser_drag Perform drag and drop between two elements

Arguments

endElement: string Human-readable target element description used to obtain the permission to interact with the element
endTarget required: string Exact target element reference from the page snapshot, or a unique element selector
startElement: string Human-readable source element description used to obtain the permission to interact with the element
startTarget required: string Exact target element reference from the page snapshot, or a unique element selector

browser_drop Drop files or MIME-typed data onto an element, as if dragged from outside the page. At least one of "paths" or "data" must be provided.

Arguments

data: object Data to drop, as a map of MIME type to string value (e.g. {"text/plain": "hello", "text/uri-list": "https://example.com"}).
element: string Human-readable element description used to obtain permission to interact with the element
paths: array Absolute paths to files to drop onto the element.
target required: string Exact target element reference from the page snapshot, or a unique element selector

browser_evaluate Evaluate JavaScript expression on page or element

Arguments

element: string Human-readable element description used to obtain permission to interact with the element
filename: string Filename to save the result to. If not provided, result is returned as text.
function required: string () => { /* code */ } or (element) => { /* code */ } when element is provided
target: string Exact target element reference from the page snapshot, or a unique element selector

browser_file_upload Upload one or multiple files

Arguments

paths: array The absolute paths to the files to upload. Can be single file or multiple files. If omitted, file chooser is cancelled.

browser_fill_form Fill multiple form fields

Arguments

fields required: array Fields to fill in

browser_find Search the accessibility snapshot of the current page for text or a regular expression. Returns matching snapshot nodes with a few lines of surrounding context (like search snippets), each shown under its path from the root of the tree, which is cheaper than capturing the whole snapshot when you only need to locate an element and its ref.

Arguments

regex: string Regular expression to search for in the page snapshot. Matching is case-sensitive by default; wrap the pattern in slashes to add flags, e.g. "/error/i" for case-insensitive. Provide either text or regex, not both.
text: string Plain text to search for in the page snapshot (case-insensitive substring match). Provide either text or regex, not both.

browser_handle_dialog Handle a dialog

Arguments

accept required: boolean Whether to accept the dialog.
promptText: string The text of the prompt in case of a prompt dialog.

browser_hover Hover over element on page

Arguments

element: string Human-readable element description used to obtain permission to interact with the element
target required: string Exact target element reference from the page snapshot, or a unique element selector

browser_navigate Navigate to a URL

Arguments

url required: string The URL to navigate to

browser_navigate_back Go back to the previous page in the history

browser_network_request Returns full details (headers and body) of a single network request, or a single part if `part` is set. Use the number from browser_network_requests.

Arguments

filename: string Filename to save the result to. If not provided, output is returned as text.
index required: integer 1-based index of the request, as printed by browser_network_requests.
part: string Return only this part of the request. Omit to return full details. Allowed values: request-headers, request-body, response-headers, response-body

browser_network_requests Returns a numbered list of network requests since loading the page. Use browser_network_request with the number to get full details.

Arguments

filename: string Filename to save the network requests to. If not provided, requests are returned as text.
filter: string Only return requests whose URL matches this regexp (e.g. "/api/.*user").
static required: boolean Whether to include successful static resources like images, fonts, scripts, etc. Defaults to false. Default: false

browser_press_key Press a key on the keyboard

Arguments

key required: string Name of the key to press or a character to generate, such as `ArrowLeft` or `a`

browser_resize Resize the browser window

Arguments

height required: number Height of the browser window
width required: number Width of the browser window

browser_run_code_unsafe Run a Playwright code snippet. Unsafe: executes arbitrary JavaScript in the Playwright server process and is RCE-equivalent.

Arguments

code: string A JavaScript function containing Playwright code to execute. It will be invoked with a single argument, page, which you can use for any page interaction. For example: `async (page) => { await page.getByRole('button', { name: 'Submit' }).click(); return await page.title(); }`
filename: string Load code from the specified file. If both code and filename are provided, code will be ignored.

browser_select_option Select an option in a dropdown

Arguments

element: string Human-readable element description used to obtain permission to interact with the element
target required: string Exact target element reference from the page snapshot, or a unique element selector
values required: array Array of values to select in the dropdown. This can be a single value or multiple values.

browser_snapshot Capture accessibility snapshot of the current page, this is better than screenshot

Arguments

boxes: boolean Include each element's bounding box as [box=x,y,width,height] in the snapshot. Coordinates are viewport-relative, in CSS pixels (Element.getBoundingClientRect)
depth: number Limit the depth of the snapshot tree
filename: string Save snapshot to markdown file instead of returning it in the response.
target: string Exact target element reference from the page snapshot, or a unique element selector

browser_tabs List, create, close, or select a browser tab.

Arguments

action required: string Operation to perform Allowed values: list, new, close, select
index: number Tab index, used for close/select. If omitted for close, current tab is closed.
url: string URL to navigate to in the new tab, used for new.

browser_take_screenshot Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.

Arguments

element: string Human-readable element description used to obtain permission to interact with the element
filename: string File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg|webp}` if not specified. Prefer relative file names to stay within the output directory.
fullPage: boolean When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.
scale required: string Image resolution scale. "css" produces a screenshot sized in CSS pixels (smaller, consistent across devices). "device" produces a high-resolution screenshot using device pixels (larger, accounts for the device pixel ratio). Default is css. Allowed values: css, device Default: css
target: string Exact target element reference from the page snapshot, or a unique element selector
type: string Image format for the screenshot. If unset, inferred from the filename extension, otherwise png. Allowed values: png, jpeg, webp

browser_type Type text into editable element

Arguments

element: string Human-readable element description used to obtain permission to interact with the element
slowly: boolean Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.
submit: boolean Whether to submit entered text (press Enter after)
target required: string Exact target element reference from the page snapshot, or a unique element selector
text required: string Text to type into the element

browser_wait_for Wait for text to appear or disappear or a specified time to pass

Arguments

text: string The text to wait for
textGone: string The text to wait for to disappear
time: number The time to wait in seconds

Optional capabilities

Vision

Adds 6 optional MCP tools.

browser_mouse_click_xy Click mouse button at a given position

Arguments

button: string Button to click, defaults to left
clickCount: number Number of clicks, defaults to 1
delay: number Time to wait between mouse down and mouse up in milliseconds, defaults to 0
x required: number X coordinate
y required: number Y coordinate

browser_mouse_down Press mouse down

Arguments

button: string Button to press, defaults to left

browser_mouse_drag_xy Drag left mouse button to a given position

Arguments

endX required: number End X coordinate
endY required: number End Y coordinate
startX required: number Start X coordinate
startY required: number Start Y coordinate

browser_mouse_move_xy Move mouse to a given position

Arguments

x required: number X coordinate
y required: number Y coordinate

browser_mouse_up Press mouse up

Arguments

button: string Button to press, defaults to left

browser_mouse_wheel Scroll mouse wheel

Arguments

deltaX required: number X delta
deltaY required: number Y delta

PDF

Adds 1 optional MCP tool.

browser_pdf_save Save page as PDF

Arguments

filename: string File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified. Prefer relative file names to stay within the output directory.

DevTools

Adds 13 optional MCP tools.

browser_annotate Open the Playwright Dashboard in annotation mode for the current page and wait for the user to draw annotations. Returns the annotated screenshot, ARIA snapshot, and the list of annotations.

browser_hide_highlight Remove a highlight overlay previously added for the element.

Arguments

element: string Human-readable element description used when adding the highlight; must match the value passed to browser_highlight.
target: string Exact target element reference from the page snapshot, or a unique element selector

browser_highlight Show a persistent highlight overlay around the element on the page.

Arguments

element: string Human-readable element description used to obtain permission to interact with the element
style: string Additional inline CSS applied to the highlight overlay, e.g. "outline: 2px dashed red".
target required: string Exact target element reference from the page snapshot, or a unique element selector

browser_resume Resume script execution after it was paused. When called with step set to true, execution will pause again before the next action.

Arguments

location: string Pause execution at a specific <file>:<line>, e.g. "example.spec.ts:42".
step: boolean When true, execution will pause again before the next action, allowing step-by-step debugging.

browser_start_recording Start recording actions that the user performs in the browser as Playwright code. Use it when the user wants to demonstrate a flow manually. Call browser_stop_recording when the user says they are done to retrieve the recorded actions.

browser_start_tracing Start trace recording

browser_start_video Start video recording

Arguments

filename: string Filename to save the video.
size: object Video size

browser_stop_recording Stop the recording started with browser_start_recording and return the recorded actions as Playwright code.

browser_stop_tracing Stop trace recording

browser_stop_video Stop video recording

browser_video_chapter Add a chapter marker to the video recording. Shows a full-screen chapter card with blurred backdrop.

Arguments

description: string Chapter description
duration: number Duration in milliseconds to show the chapter card
title required: string Chapter title

browser_video_hide_actions Stop annotating actions performed on the page.

browser_video_show_actions Annotate subsequent actions performed on the page with a callout that names the action and highlights the target element. Useful while video recording or screencasting.

Arguments

cursor: string Cursor decoration for pointer actions. "pointer" (default) animates a mouse pointer from the previous action point to the next one; "none" disables the cursor decoration.
duration: number How long each action annotation stays on screen, in milliseconds. Defaults to 500.
position: string Where to place the action title relative to the page. Defaults to top-right.

What it does

Available functions

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Optional capabilities

Vision

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

PDF

Arguments

DevTools

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Questions people ask

Let the agent test the code it changed.