Better Playwright

You operate a high-performance Playwright MCP server that enables automated browser control via a compact, reference-based element system, fast regex-driven content search, and intelligent DOM compression. This server pairs an MCP interface with an HTTP controller to deliver scalable browser automation for AI-assisted workflows and testing pipelines.

How to use

To start using the MCP server, first run the HTTP server, then launch the MCP server in a separate process. The HTTP server exposes the browser control surface, while the MCP server talks to clients using the Model Context Protocol.

Typical workflow you will follow each time you automate a page:

In your client code, connect to the MCP server and create a page, then use the provided methods to navigate, interact with elements via ref identifiers, search content, and capture results.

Key actions you can perform after establishing a page context include creating pages, navigating, clicking, typing, scrolling, waiting for elements, and taking screenshots. You can also generate an intelligent, folded outline of the page structure to guide precise actions and efficient searches.

How to install

Prerequisites: You need Node.js v18 or newer and a compatible browser (Chrome/Chromium). Then install the MCP server tooling and run the server as described.

npm install -g better-playwright-mcp3

npm install better-playwright-mcp3

Usage details and practical notes

There are two primary modes you can use to run the MCP setup. The HTTP server serves as the control plane for the browser, and the MCP server handles protocol messages from AI assistants or clients.

Start the HTTP server and then start the MCP server in another terminal. The MCP server connects to the HTTP server on port 3102 and routes browser automation commands accordingly.

# Start the HTTP server
npx better-playwright-mcp3@latest server

# In another terminal, start the MCP server
npx better-playwright-mcp3@latest

Configuration and troubleshooting

If you encounter issues, check that the HTTP server is reachable, the browser is installed, and the environment has sufficient resources. When elements cannot be found, verify the ref identifiers from the page outline and use content search to locate targets.

If a port is in use or a browser fails to launch, adjust the port or browser flags, and ensure the target process has permission to launch a browser.

Examples

Creating a page and navigating to a URL, then performing actions through ref identifiers, is a common pattern. You will typically create a page, obtain a pageId, fetch an outline, and then drive interactions using element refs discovered in the outline.

Available tools

createPage

Create a new browser page with a name and description, returning a pageId for subsequent operations.

closePage

Close a specific page by its pageId to free resources.

listPages

List all managed pages with titles and URLs for quick reference.

browserNavigate

Navigate a given page to a specified URL.

browserNavigateBack

Navigate back in the page's history.

browserNavigateForward

Navigate forward in the page's history.

scrollToBottom

Scroll to the bottom of the current page or to a specific element.

scrollToTop

Scroll to the top of the current page or to a specific element.

waitForTimeout

Pause execution for a given number of milliseconds.

waitForSelector

Wait for a specific selector to appear before continuing.

browserClick

Click an element identified by its ref ID.

browserType

Type text into an input element identified by its ref ID.

browserHover

Hover the mouse over an element identified by its ref ID.

browserSelectOption

Select an option within a dropdown for a given element.

fill

Fill an input or textarea with the provided value.

browserPressKey

Simulate pressing a keyboard key.

browserFileUpload

Upload a file to a file input element.

browserHandleDialog

Handle dialogs such as alert, confirm, or prompt.

getOutline

Get an intelligently compressed outline of the current page structure with list folding.

searchSnapshot

Search page content using regex patterns (powered by ripgrep) and return matches.

screenshot

Capture a screenshot of the page in PNG or JPEG format.