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, work with tabs, frames, cookies and requests. Twenty-four 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 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.