Skip to main content
Glama
mcp-playwright-tools

mcp-playwright-tools

by cuber-it

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, placeholder or testid.

  • 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 along

A 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 chrome

As 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.png

Tools

Tool

What it does

open_url

Open a page and wait until its document has loaded

go

Back, forward or reload

where_am_i

Address, title, tab, frame, the frames of the page, viewport

tabs

List, open, switch or close tabs, those a page opened included

use_frame

Act inside a frame, also one inside a frame, or in the page again

viewport

Report or set the size of the page area

find

Count and list the elements that match

describe

Tag, text, attributes and state of one element

what_can_i_do

Everything visible on the page that can be acted on

outline

The accessibility tree

click

Click an element

act_on

Double-click, right-click, hover, focus, check, uncheck, clear, scroll to

fill

Put text into a field, at once or key by key

press_key

Press a key on an element or on the page

choose

Choose an option in a dropdown

drag

Drag one element onto another

scroll

Scroll down, up, to the top or to the bottom

attach_files

Put files from the machine into a file input

run_javascript

Run JavaScript in the page

read

Text, the text of every match, markup, an attribute, the links

screenshot

A picture of the page or of one element, a PNG file, or a PDF

wait_until

Wait for an element, an address, a load state or a response

storage

Get, set or clear cookies and the local storage

intercept

Mock, block or release requests of the page

contexts

The browser and its contexts; open one as a device or from a saved state, save one, close one or all

logs

Console messages and page errors, responses and failed requests, dialogs

dialogs

Accept or dismiss alerts, confirms and prompts, with an answer for prompts

downloads

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 (guarded)

reading

open_url with a file: address, contexts opening a state file

anywhere

writing

screenshot and downloads with save_to, contexts saving a state file

inside the allowed roots and /tmp

uploading

attach_files

from the working directory and /tmp

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 reset

Details in doc/boundary.md.

Server options

Option

Default

Meaning

--transport

stdio

stdio or streamable-http

--host

MCP_HOST, else 127.0.0.1

address to bind (HTTP)

--port

MCP_PORT, else 8000

port to bind (HTTP)

--path

/mcp

path the endpoint answers on (HTTP)

--working-dir

current directory

where relative paths start and files are uploaded from

--allowed-root

home directory

where files may be written besides /tmp; repeatable

--state-dir

~/.mcp-playwright-tools

where the grant is kept; empty for no grants

--mode

guarded

open, guarded or strict

--browser

chromium

chromium, firefox or webkit

--channel

none

an installed browser such as chrome

--headed

off

show the browser window

--timeout

30

seconds a single action may take

--idle

900

seconds a context may go unused before it is closed; 0 keeps them

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 tools
abort_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_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_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_hiddenC

Wait for an element to disappear

Inputs: selector (required), timeout. 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

    C2.8/5.0

    Scored across 73 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP clients to automate a real Chrome browser via Playwright, supporting session sharing and tools for navigation, clicking, typing, and more.
      11
      108 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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 npm
      MIT