mcp-playwright-tools
This server provides browser automation tools for AI assistants, allowing navigation, interaction, page inspection, screenshots, tab/frame management, network/console monitoring, and more.
Navigate to URLs, back/forward/reload, get current URL and title
Extract page content: visible text, HTML, links, attributes, ARIA accessibility snapshot, console messages, network requests
Interact with elements: click, double-click, right-click, hover, focus, fill, type, press keys, select dropdown options, check/uncheck, clear, drag-and-drop, upload files
Locate elements by CSS selector, ARIA role, visible text, label, placeholder, or test ID
Take screenshots of page or elements (or save to file)
Manage tabs: open, list, switch, close
Work with frames: switch to iframe, return to main frame
Control viewport, scrolling, browser type, headless mode, video recording
Wait for elements, URL patterns, network responses, and downloads
Handle browser cookies and localStorage
Mock, block, or abort network routes
Accept/dismiss dialogs, interact with downloads
Execute JavaScript in page context
Discover interactive elements and describe element details
Allows driving a Firefox browser for web automation, including navigation, interacting with elements, reading page content, taking screenshots, and managing tabs, dialogs, downloads, console messages, and network requests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-playwright-tools open https://example.com and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-playwright-tools
Version 8.0 — completely rewritten and revised.
Browser tools for AI assistants: open pages, find and act on elements, read what is there, take screenshots and PDFs, work with tabs, frames, cookies, requests, dialogs and downloads, read the console and the network log. Twenty-eight tools, usable as a Python library, from the shell, or served over the Model Context Protocol.
The way of pointing is a parameter. Every tool that works on an element takes
by:css,role,text,label,placeholderortestid.Contexts by name. Every tool takes
context. Each name is a browser context with its own cookies, storage and tabs, closed when nobody has used it for a while; the browser stops with the last one. A context can pass for a device such as a phone, and its login can be saved and used again.Nothing gets lost: tabs a page opens itself are listed and become the active tab; console messages, responses, dialogs and downloads are recorded from the moment a context opens.
A screenshot arrives as a picture, an image content block.
Boundary: nothing inside the browser needs a permission. Screenshots are written inside the allowed roots and
/tmp, files are uploaded from the working directory and/tmp; a person on the host widens that for a limited time with a grant.Server over stdio or streamable HTTP with the MCP SDK, protocol revision 2026-07-28, OAuth for HTTP.
Installation
Python 3.12 or later.
pip install mcp-playwright-tools # the library and pw-browse
pip install "mcp-playwright-tools[server]" # and the MCP server
playwright install chromium # the browser Playwright brings alongA Chrome already installed on the machine works as well: pass
--channel chrome instead of installing a browser.
Related MCP server: BugScout MCP Server
Quick start
A client that starts the server itself, over stdio:
{
"mcpServers": {
"playwright": {
"command": "mcp-playwright-tools",
"args": ["--channel", "chrome"]
}
}
}Over HTTP, with OAuth:
MCP_OAUTH_ENABLED=true \
MCP_OAUTH_SERVER_URL=https://auth.example.org/ \
MCP_PUBLIC_URL=https://mcp.example.org/ \
mcp-playwright-tools --transport streamable-http --host 0.0.0.0 --port 12206 \
--path /playwright --channel chromeAs a library:
import asyncio
from pathlib import Path
from mcp_playwright_tools import Workspace, navigate, read
async def main():
space = Workspace(working_dir=Path.cwd())
here = space.browsing() # the context named "default"
print(await navigate.open_url(here, "example.org"))
print(await read.read(here, "h1"))
await space.pool.close_all()
asyncio.run(main())From the shell, one run with a fixed order: open, fill, click, wait, show:
pw-browse example.org --text h1
pw-browse example.org --click "Learn more" --by text --url
pw-browse example.org --shot page.pngTools
Tool | What it does |
| Open a page and wait until its document has loaded |
| Back, forward or reload |
| Address, title, tab, frame, the frames of the page, viewport |
| List, open, switch or close tabs, those a page opened included |
| Act inside a frame, also one inside a frame, or in the page again |
| Report or set the size of the page area |
| Count and list the elements that match |
| Tag, text, attributes and state of one element |
| Everything visible on the page that can be acted on |
| The accessibility tree |
| Click an element |
| Double-click, right-click, hover, focus, check, uncheck, clear, scroll to |
| Put text into a field, at once or key by key |
| Press a key on an element or on the page |
| Choose an option in a dropdown |
| Drag one element onto another |
| Scroll down, up, to the top or to the bottom |
| Put files from the machine into a file input |
| Run JavaScript in the page |
| Text, the text of every match, markup, an attribute, the links |
| A picture of the page or of one element, a PNG file, or a PDF |
| Wait for an element, an address, a load state or a response |
| Get, set or clear cookies and the local storage |
| Mock, block or release requests of the page |
| The browser and its contexts; open one as a device or from a saved state, save one, close one or all |
| Console messages and page errors, responses and failed requests, dialogs |
| Accept or dismiss alerts, confirms and prompts, with an answer for prompts |
| List what was downloaded, save a download |
A value that is not allowed is refused with the allowed ones named.
Boundary and grants
Everything the tools do inside the browser is free, run_javascript included.
Three things reach the machine the browser runs on:
Access | Tools | Without a grant ( |
reading |
| anywhere |
writing |
| inside the allowed roots and |
uploading |
| from the working directory and |
strict confines reading to the roots as well, open lifts every limit. A
refusal names the grant that lifts it, to be run by a person on the host:
scripts/grant.sh set --root ~/Downloads --for 30m
scripts/grant.sh show
scripts/grant.sh resetDetails in doc/boundary.md.
Server options
Option | Default | Meaning |
|
|
|
|
| address to bind (HTTP) |
|
| port to bind (HTTP) |
|
| path the endpoint answers on (HTTP) |
| current directory | where relative paths start and files are uploaded from |
| home directory | where files may be written besides |
|
| where the grant is kept; empty for no grants |
|
|
|
|
|
|
| none | an installed browser such as |
| off | show the browser window |
|
| seconds a single action may take |
|
| seconds a context may go unused before it is closed; |
Authentication over HTTP is configured with MCP_OAUTH_ENABLED,
MCP_OAUTH_SERVER_URL, MCP_PUBLIC_URL and MCP_AUTH_METHOD; the server
refuses to listen beyond this machine without it.
Development
Setup, checks, release steps and the rules the code keeps: doc/development.md. Changes are listed in CHANGES.md.
License
MIT, see LICENSE.
Available Tools
73 toolsabort_routeC
Block requests matching url_pattern
Inputs: url_pattern (required). Returns: result
accept_dialogA
Accept the next browser dialog
Inputs: no named parameters. Returns: result
checkC
Check a checkbox
Inputs: selector (required). Returns: result
clearC
Clear an input field
Inputs: selector (required). Returns: result
clear_cookiesA
Clear all cookies
Inputs: no named parameters. Returns: result
clear_routeC
Remove a route mock
Inputs: url_pattern (required). Returns: result
clear_storageA
Clear localStorage and sessionStorage
Inputs: no named parameters. Returns: result
clickC
Click an element
Inputs: selector (required). Returns: result
click_by_roleC
Click element by ARIA role
Inputs: role (required), name. Returns: result
click_by_textC
Click element by visible text
Inputs: text (required). Returns: result
close_tabC
Close a tab by ID
Inputs: tab_id (required). Returns: result
current_urlA
Get the current page URL
Inputs: no named parameters. Returns: result
describe_elementC
Get ARIA role, text, and attributes of an element
Inputs: selector (required). Returns: result
dismiss_dialogB
Dismiss the next browser dialog
Inputs: no named parameters. Returns: result
double_clickC
Double-click an element
Inputs: selector (required). Returns: result
drag_and_dropC
Drag element from source to target
Inputs: source (required), target (required). Returns: result
execute_scriptC
Execute JavaScript in the page context
Inputs: code (required). Returns: result
fillC
Fill an input field
Inputs: selector (required), text (required). Returns: result
fill_by_labelC
Fill input found by its label
Inputs: label (required), value (required). Returns: result
find_by_labelC
Find form element by label
Inputs: label (required). Returns: result
find_by_placeholderC
Find input by placeholder
Inputs: placeholder (required). Returns: result
find_by_roleC
Find element by ARIA role
Inputs: role (required), name. Returns: result
find_by_test_idC
Find element by data-testid
Inputs: test_id (required). Returns: result
find_by_textC
Find element by visible text
Inputs: text (required), exact. Returns: result
find_interactive_elementsA
List all clickable and fillable elements on the page
Inputs: no named parameters. Returns: result
focusD
Focus an element
Inputs: selector (required). Returns: result
get_all_textsC
Get visible text of all matching elements
Inputs: selector (required). Returns: result
get_aria_snapshotB
Get ARIA accessibility tree as YAML — ideal for LLM navigation
Inputs: selector. Returns: result
get_attributeC
Get an attribute value from an element
Inputs: selector (required), attribute (required). Returns: result
get_console_messagesA
Get recent console messages from the page
Inputs: no named parameters. Returns: result
get_cookiesB
Get all cookies
Inputs: no named parameters. Returns: result
get_htmlB
Get inner HTML of an element
Inputs: selector. Returns: result
get_linksA
Get all links on the page
Inputs: no named parameters. Returns: result
get_local_storageB
Get localStorage — all items or a specific key
Inputs: key. Returns: result
get_page_contentC
Get all visible text on the page
Inputs: max_length. Returns: result
get_page_requestsB
Get recent network requests made by the page
Inputs: no named parameters. Returns: result
get_textC
Get visible text of an element
Inputs: selector (required). Returns: result
get_titleB
Get the page title
Inputs: no named parameters. Returns: result
go_backB
Navigate back in browser history
Inputs: no named parameters. Returns: result
go_forwardA
Navigate forward in browser history
Inputs: no named parameters. Returns: result
hoverC
Hover over an element
Inputs: selector (required). Returns: result
list_tabsA
List all open tabs
Inputs: no named parameters. Returns: result
mock_routeC
Mock network requests matching url_pattern
Inputs: url_pattern (required), status, body, content_type. Returns: result
new_tabB
Open a new browser tab
Inputs: no named parameters. Returns: result
pressA
Press a key — on element if selector given, else globally
Inputs: key (required), selector. Returns: result
recording_show_actionsC
Annotate recording with action highlights
Inputs: position. Returns: result
reloadA
Reload the current page
Inputs: no named parameters. Returns: result
right_clickC
Right-click an element
Inputs: selector (required). Returns: result
screenshotC
Take a screenshot — returns base64 if no path given
Inputs: path, full_page. Returns: result
screenshot_elementC
Take a screenshot of a specific element
Inputs: selector (required), path. Returns: result
scroll_pageC
Scroll page — direction: up/down/top/bottom
Inputs: direction, amount. Returns: result
scroll_toC
Scroll element into view
Inputs: selector (required). Returns: result
select_optionC
Select a dropdown option by value
Inputs: selector (required), value (required). Returns: result
select_option_by_textC
Select a dropdown option by visible text
Inputs: selector (required), text (required). Returns: result
set_browserB
Switch browser: chromium, firefox, or webkit
Inputs: browser_type (required). Returns: result
set_cookieC
Set a cookie
Inputs: name (required), value (required), domain, path. Returns: result
set_headlessC
Switch between headless and headed mode
Inputs: headless (required). Returns: result
set_local_storageC
Set a localStorage item
Inputs: key (required), value (required). Returns: result
set_viewportB
Set browser viewport size
Inputs: width (required), height (required). Returns: result
start_recordingC
Start video recording
Inputs: path. Returns: result
stop_recordingA
Stop video recording and save
Inputs: no named parameters. Returns: result
switch_tabC
Switch to a tab by ID
Inputs: tab_id (required). Returns: result
switch_to_frameC
Switch context to an iFrame
Inputs: selector (required). Returns: result
switch_to_mainA
Switch back to main frame
Inputs: no named parameters. Returns: result
type_textA
Type text character by character (for autocomplete)
Inputs: selector (required), text (required), delay. Returns: result
uncheckC
Uncheck a checkbox
Inputs: selector (required). Returns: result
upload_fileC
Upload a file to a file input
Inputs: selector (required), path (required). Returns: result
wait_forC
Wait for an element to appear
Inputs: selector (required), timeout. Returns: result
wait_for_downloadC
Click trigger and wait for file download
Inputs: trigger_selector. Returns: result
wait_for_responseC
Wait for a network response
Inputs: url_pattern (required), timeout. Returns: result
wait_for_urlC
Wait for URL to match a pattern
Inputs: url_pattern (required), timeout. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 73 tools
Tools are mostly distinct with clear descriptions, but there are multiple variants for clicks (click, click_by_role, click_by_text, double_click, right_click) and finds (find_by_label, find_by_placeholder, etc.) which could cause confusion if descriptions are not read carefully.
Tool names follow a consistent verb_noun or verb_preposition_noun pattern with lowercase and underscores. Even single-word verbs (e.g., click, fill) are uniform. The naming is predictable and clear.
With 73 tools, the count far exceeds the typical scope for a tool server. While browser automation is complex, many tools could be consolidated (e.g., merging click variants). This volume risks overwhelming agents.
The set covers a broad range of browser automation tasks: navigation, form interaction, waiting, cookies, storage, frames, dialogs, and recording. Minor gaps exist (e.g., no device emulation or performance metrics), but core workflows are well-supported.
Maintenance
Related MCP Connectors
Playwright browser automation — navigate, click, fill forms, extract, screenshot — 17 agent tools.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
MCPs that do tasks on any website. Search flights, book, shop, check accounts and fill in forms.
Related MCP Servers
- FlicenseBqualityDmaintenancePlaywright wrapper for MCP that enables LLM-powered clients to control a browser for automation tasks.101-
- AlicenseNot gradedqualityDmaintenanceEnables autonomous web QA by exposing Playwright browser control as MCP tools for navigation, accessibility snapshotting, interaction, and bug detection.MIT
- AlicenseAqualityDmaintenanceEnables MCP clients to automate a real Chrome browser via Playwright, supporting session sharing and tools for navigation, clicking, typing, and more.11108 npm2MIT
- AlicenseNot gradedqualityDmaintenanceAn enhanced MCP Playwright browser server that enables robust web automation with persistent locator caching, multi-level click fallbacks, accessibility tree interactions, and smart handling of navigation and popups.374 npmMIT