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.

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

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.