Browser, group and page tools, side by side.
MCP Playwright gives your agent two kinds of tools: browser and group tools written for this service, and the page tools of the Playwright MCP server (read, click, type and so on), which each take one added browserId parameter so a call names the browser it acts on. Two page tools, browser_run_code_unsafe and browser_get_config, are not exposed. Your client's tool list is the authority for what is available, because the page tools come from the installed integration and can differ between versions.
Start, list and stop browsers.
| Tool | Use it to | Parameters |
|---|---|---|
browser_start | Start one browser, Chromium or Firefox, and get back its browser id. This is how a browser gets its id, so one session can hold several browsers at once. | browser (required: chromium or firefox), env (optional object of string overrides) |
browser_list | See which browsers are running in this session, each with its id. | none |
browser_stop | End one browser, finish its video recording and publish its last resources. | browserId (required) |
browser_close | Close only the current page; the browser keeps running | browserId (required) |
Why: start one browser per account, engine or viewport you need to keep apart; each has its own page and website state. List before you reuse an id, and stop what you started: stopping is also what finalizes a video recording.
Only browser and env are advertised on browser_start. The service also accepts the structured options below when your client can send them; each one becomes one PLAYWRIGHT_MCP_* variable for that browser, and an explicit env entry wins on conflict.
| Option | Variable | Use it to |
|---|---|---|
initialUrl | none | Load a first page at launch; the default is a blank page. |
gpu | PLAYWRIGHT_MCP_GPU | Choose how the browser renders: automatic, off, or a hardware path for Apple, Linux GPU devices (dri), WSL2 GPU (dxg), NVIDIA or ROCm. The start fails if a known software renderer shows up on a hardware path. |
viewport_size | PLAYWRIGHT_MCP_VIEWPORT_SIZE | Fix the viewport at start, such as 390x844 |
device | PLAYWRIGHT_MCP_DEVICE | Emulate a phone or tablet, such as iPhone 15 |
user_agent | PLAYWRIGHT_MCP_USER_AGENT | Present a specific browser identity |
save_video | PLAYWRIGHT_MCP_SAVE_VIDEO | Record the whole session as a WebM video at the size you give. The recording is finished and published as a resource when you stop the browser. |
storage_state, save_session | PLAYWRIGHT_MCP_STORAGE_STATE, PLAYWRIGHT_MCP_SAVE_SESSION | Start signed in from a saved state; save session state on stop |
isolated | PLAYWRIGHT_MCP_ISOLATED | Run in an isolated context |
proxy_server, proxy_bypass | PLAYWRIGHT_MCP_PROXY_SERVER, PLAYWRIGHT_MCP_PROXY_BYPASS | Route traffic through a proxy; skip it for listed domains |
grant_permissions | PLAYWRIGHT_MCP_GRANT_PERMISSIONS | Pre-approve browser permissions, such as geolocation |
timeout_action, timeout_navigation | PLAYWRIGHT_MCP_TIMEOUT_ACTION, PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION | Tune how long actions and navigations may take (ms) |
console_level | PLAYWRIGHT_MCP_CONSOLE_LEVEL | Capture only messages at or above a level |
init_script | PLAYWRIGHT_MCP_INIT_SCRIPT | Run a script before every page |
snapshot_mode, output_mode, caps, test_id_attribute | PLAYWRIGHT_MCP_* | Adjust snapshots, output, capabilities and the test-id attribute |
HEADLESS is set through env: "false" opens a visible window and needs a display your environment already provides.
Read what is on the page.
| Tool | Use it to | Key parameters |
|---|---|---|
browser_snapshot | Read the page as accessible text with element references. With filename the snapshot is saved inside the session and published as a resource. Upstream tool. | depth, boxes (bounding boxes), target, filename, browserId |
browser_find | Locate text or a pattern in the snapshot without reading all of it | text or regex (one of them) |
browser_take_screenshot | Capture the page or one element. The image is published as a resource and left out of the reply unless you pass inlineImage; images over 512 KiB stay resource-only. Upstream tool. | type (png, jpeg, webp), fullPage, target, scale (css or device), filename, inlineImage (default false), browserId |
browser_evaluate | Run JavaScript in the page and return the result | function (required), target, filename |
browser_console_messages | Read console output | level (required: error, warning, info, debug), all, filename |
browser_network_requests | List requests since the page loaded | static (required), filter (URL pattern), filename |
browser_network_request | Read the full detail of one listed request | index (required, from the list), part, filename |
browser_generate_locator | Get a stable locator for an element, for test code | target |
browser_pdf_save | Save the page as a PDF. Saved inside the session and published as a resource you fetch by address. Upstream tool. | filename, browserId |
Why: prefer browser_snapshot and browser_find for understanding a page, since they return text, and use browser_take_screenshot when the appearance is the question or you need evidence for a person. Read browser_console_messages and browser_network_requests when something looks wrong. Screenshots, PDFs, traces and videos are published as resources: read the exact address the result returns instead of expecting image data in the reply. Pass inlineImage: true to get the image in the reply too; images over 512 KiB (the default MCP_INLINE_IMAGE_MAX_BYTES) are still returned as a resource only. For the tools that write files (browser_snapshot, browser_take_screenshot, browser_pdf_save, tracing and video), filename must be relative, without .., and inside a group call it gains the browser id as a suffix.
Click, type and move through pages.
| Tool | Use it to | Key parameters |
|---|---|---|
browser_navigate, browser_navigate_back | Open a URL or go back | url |
browser_click | Click, double-click or right-click | target (required), button, doubleClick, modifiers |
browser_type | Type into an editable element | target, text (required), submit (press Enter), slowly |
browser_fill_form | Fill several fields at once | fields: list of name, type (textbox, checkbox, radio, combobox, slider), target, value |
browser_select_option | Choose option values in a dropdown | target, values |
browser_press_key | Send a key such as ArrowLeft or Enter | key |
browser_hover, browser_drag, browser_drop | Hover, drag between elements or drop | target; startTarget and endTarget for drag |
browser_mouse_click_xy, browser_mouse_move_xy, browser_mouse_drag_xy, browser_mouse_down, browser_mouse_up, browser_mouse_wheel | Act by coordinates when an element has no usable reference | coordinates |
browser_file_upload | Upload files through a file chooser | paths: absolute paths on the service host |
browser_handle_dialog | Accept or dismiss an alert, confirm or prompt | accept (required), promptText |
browser_wait_for | Wait for text to appear or vanish, or for time to pass | text, textGone, time (seconds) |
browser_tabs | List, open, close or select a tab | action (required: list, new, close, select), index, url |
browser_resize | Change the window size | width, height |
browser_resume | Resume a run that was paused, optionally one step at a time | step, location |
Why: target is the element reference from the latest browser_snapshot, or a unique selector; the optional element is a human description that helps your client ask for permission. Actions can change real accounts and uploads read files from the service host, so keep to the task's authorized scope.
Keep sign-in state and shape the network.
| Tool | Use it to | Key parameters |
|---|---|---|
browser_storage_state | Save cookies and local storage to a file | filename |
browser_set_storage_state | Restore a saved state into a browser | the state file |
browser_cookie_list, _get, _set, _delete, _clear | Work with cookies | name, value (required to set); domain, path, expires, httpOnly, secure, sameSite |
browser_localstorage_*, browser_sessionstorage_* | List, read, set, delete or clear storage entries | key and value |
browser_route, browser_route_list, browser_unroute | Mock responses for matching requests | pattern (required), status, body, contentType, headers, removeHeaders |
browser_network_state_set | Go offline or back online | state (online or offline) |
Why: save a signed-in state once and restore it into later browsers instead of logging in again, and treat the file as a credential. Route and offline mode let you test failure paths, such as a slow or failing API, without touching the real service.
Check that the page shows what you expect.
| Tool | Use it to | Key parameters |
|---|---|---|
browser_verify_text_visible | Assert that text is visible | text |
browser_verify_element_visible, browser_verify_list_visible, browser_verify_value | Assert an element, a list or a field value | element references and expected values |
Why: an assertion tool fails loudly where reading a snapshot relies on judgement. A successful call still only says the check passed on that page state.
Record the run and mark up the page.
| Tool | Use it to | Key parameters |
|---|---|---|
browser_start_video, browser_stop_video | Record a video and finish it. The finished files are published as resources, one per open page. Upstream tool. | size (width, height), filename, browserId |
browser_video_chapter | Add a chapter card to the recording | title (required), description, duration (ms) |
browser_video_show_actions, browser_video_hide_actions | Show or hide action overlays in the recording | none |
browser_start_tracing, browser_stop_tracing | Capture a trace for later inspection. The trace file is published as a resource. Upstream tool. | browserId |
browser_start_recording, browser_stop_recording | Record the actions you perform as Playwright code. The code is also published as a resource you can fetch. Upstream tool. | browserId |
browser_annotate | Let you draw annotations on the page and return them with a screenshot | none |
browser_highlight, browser_hide_highlight | Show a persistent outline around an element | target, style |
Why: video and trace give reviewers the run; recording turns a flow you perform into code; annotation lets you point at the problem. Video can contain private page content.
Run one call across several browsers.
| Tool | Use it to | Parameters |
|---|---|---|
browser_group_create | Name an ordered set of running browsers so you can drive them together. Groups exist only in MCP Playwright. | groupId, browserIds (both required) |
browser_group_call | Run one page tool across every browser in a group. You get one result per browser, and the browser id is added to every saved file name so members do not overwrite each other. | groupId, tool (required, any page tool), args, perBrowser |
browser_group_list | List your groups and their members. | none |
browser_group_delete | Remove a group; its browsers keep running. | groupId |
browser_group_close | Stop every browser in a group, and by default delete the group as well. | groupId, deleteGroup (default true) |
{ "groupId": "comparison", "tool": "browser_take_screenshot",
"args": { "type": "jpeg", "filename": "cross-engine.jpg" } }The result is { groupId, summary: { total, ok, errors }, results: [ { browserId, ok, result | error } ], firstError? }: one full result per browser. args apply to every member and perBrowser merges extra arguments for one browser only. File-saving tools get the browser id appended to their filename so members do not collide, and calls run with bounded concurrency (MCP_GROUP_MAX_CONCURRENCY, default 8). A group id that names a single browser behaves like a direct call. There is no rollback across browsers, and grouped captures do not publish per-member resources, so capture each browser directly when you need resource addresses.