mcp-playwright-tools

mcp-playwright-tools

Version 8.0 — completely rewritten and revised.

Browser tools for AI assistants: open pages, find and act on elements, readwhat 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 overthe Model Context Protocol.

• The way of pointing is a parameter. Every tool that works on an elementtakes by: css, role, text, label, placeholder or testid.
• Contexts by name. Every tool takes context. Each name is a browsercontext with its own cookies, storage and tabs, closed when nobody has usedit for a while; the browser stops with the last one. A context can pass fora 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 theactive tab; console messages, responses, dialogs and downloads are recordedfrom the moment a context opens.
• A screenshot arrives as a picture, an image content block.
• Boundary: nothing inside the browser needs a permission. Screenshots arewritten inside the allowed roots and /tmp, files are uploaded from theworking directory and /tmp; a person on the host widens that for a limitedtime with a grant.
• Server over stdio or streamable HTTP with the MCP SDK, protocol revision2026-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.

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

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:

strict confines reading to the roots as well, open lifts every limit. Arefusal 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 indoc/boundary.md.

Server options

Authentication over HTTP is configured with MCP_OAUTH_ENABLED,MCP_OAUTH_SERVER_URL, MCP_PUBLIC_URL and MCP_AUTH_METHOD; the serverrefuses to listen beyond this machine without it.

Development

Setup, checks, release steps and the rules the code keeps:doc/development.md.Changes are listed inCHANGES.md.

License

MIT, seeLICENSE.