Playwright MCP
What is Playwright MCP?
Playwright MCP is a server that lets an AI assistant control a real web browser.
An AI assistant (or AI agent) is a program, like Claude, Copilot or ChatGPT, that reads your request and then does the work in steps, using tools.
MCP means Model Context Protocol.
It is a standard way for an AI assistant to find and use tools that other programs offer.
A program that offers tools this way is called an MCP server.
The AI app that uses the tools (for example Claude Code or VS Code) is called an MCP client.
The Playwright MCP server offers tools like "open this URL", "click this button" and "type this text".
The AI calls these tools, and Playwright does the work in the browser.
So you can ask the AI: "Open the todo page, add a todo, and check that the counter says 1 item left".
How the AI Sees the Page
The AI does not look at pictures of the page.
It reads an accessibility snapshot: a text list of the elements on the page, with their role, name and state.
This is the same information a screen reader uses, and the same roles and names that getByRole() uses (see Locators).
Here is a part of the snapshot of the Todo practice page:
- main [ref=e9]:
- heading "Todo List" [level=1] [ref=e10]
- generic [ref=e11]:
- generic [ref=e12]: New todo
- textbox "New todo" [ref=e13]:
- /placeholder: What needs to be done?
- paragraph [ref=e14]:
- button "Add" [ref=e15] [cursor=pointer]
- group "Filter" [ref=e16]:
- button "All" [pressed] [ref=e17] [cursor=pointer]
- button "Active" [ref=e18] [cursor=pointer]
- button "Done" [ref=e19] [cursor=pointer]
- list "Todos"
- paragraph [ref=e20]: 0 items left
Each element has a ref, like e13.
A ref is a short name for one element in the snapshot.
When the AI wants to type into the "New todo" box, it tells the click or type tool to use e13.
Why is a text snapshot better than a screenshot?
- It is small, so the AI can read it fast and cheaply
- It is exact: the AI does not have to guess where a button is from the pixels
- Any AI model can read text, so you do not need a model that understands images
Screenshots are still available when the AI needs to check how the page looks.
Connect Playwright MCP to Your AI App
You need Node.js 20 or newer, and an AI app that supports MCP.
Most apps read a JSON configuration like this one:
Example
MCP configuration
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
It tells the app to start the server with the command npx @playwright/mcp@latest.
@playwright/mcp is the npm package with the Playwright MCP server, and @latest means "the newest version".
Where this JSON goes depends on the app (Cursor, Claude Desktop, Windsurf and others).
Check the documentation of your app.
In Claude Code, add the server with one command:
Example
claude mcp add playwright npx @playwright/mcp@latest
In VS Code, run this command in a terminal:
Example
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
The Playwright MCP page on GitHub also has install buttons for VS Code and Cursor.
Use the Playwright You Already Have
Playwright 1.65 also has the MCP server built in, as npx playwright mcp.
If your project already has Playwright installed, you can use it instead of the separate package:
Example
MCP configuration
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["playwright", "mcp"]
}
}
}
Then the server uses the same Playwright version and browsers as your tests.
Most guides on the web use @playwright/mcp.
Both give you the same tools.
Note: By default, the server opens a visible browser window, so you can watch what the AI does.
Add the --headless option to hide it (see Useful Options below).
The Main Tools
The server gives the AI about 25 tools.
These are the ones it uses most:
| Tool | What it does |
|---|---|
| browser_navigate | Opens a URL |
| browser_snapshot | Returns the accessibility snapshot of the page |
| browser_click | Clicks an element (by its ref) |
| browser_type | Types text into an element, and can press Enter after it |
| browser_fill_form | Fills several form fields in one call (text boxes, checkboxes, radio buttons, selects) |
| browser_select_option | Selects an option in a drop-down list |
| browser_press_key | Presses a key, like Enter or Escape |
| browser_wait_for | Waits for a text to appear or disappear, or for a number of seconds |
| browser_take_screenshot | Takes a screenshot of the page or of one element |
| browser_tabs | Lists, opens, closes or selects browser tabs |
| browser_console_messages | Returns the messages the page wrote to the browser console |
| browser_network_requests | Lists the network requests the page sent |
| browser_navigate_back | Goes back to the previous page |
| browser_close | Closes the page |
The AI app asks the server for the list of tools when it starts, so you do not have to tell the AI about them.
Example: An AI Adds a Todo
You ask the AI: "Add the todo Buy milk on the practice todo page".
These are the real tool calls, and parts of the real responses the AI gets back.
Step 1: The AI opens the page with browser_navigate:
browser_navigate
{ "url": "https://www.w3schools.com/playwright/practice/todo.html" }
The response:
### Ran Playwright code
```js
await page.goto('https://www.w3schools.com/playwright/practice/todo.html');
```
### Page
- Page URL: https://www.w3schools.com/playwright/practice/todo.html
- Page Title: Todo List | Playwright Practice
Step 2: The AI reads the page with browser_snapshot (no arguments).
The response is the snapshot you saw in "How the AI Sees the Page".
From it, the AI learns that the "New todo" text box is e13 and the "Add" button is e15.
Step 3: The AI types the text with browser_type:
browser_type
{ "element": "New todo textbox", "target": "e13", "text": "Buy milk" }
The response:
### Ran Playwright code
```js
await page.getByRole('textbox', { name: 'New todo' }).fill('Buy milk');
```
Step 4: The AI clicks Add with browser_click:
browser_click
{ "element": "Add button", "target": "e15" }
The response:
### Ran Playwright code
```js
await page.getByRole('button', { name: 'Add' }).click();
```
Step 5: The AI checks the result with a new browser_snapshot.
A part of the response:
- list "Todos" [ref=e21]:
- listitem [ref=e22]:
- checkbox "Complete Buy milk" [ref=e23]
- generic [ref=e24]: Buy milk
- button "Delete Buy milk" [ref=e25] [cursor=pointer]: Delete
- paragraph [ref=e20]: 1 item left
The new todo is in the list, and the counter says "1 item left".
The AI can tell you the task is done.
Example Explained
targetis the ref from the snapshotelementis a short description for humans. Some AI apps show it when they ask you to allow the action- Every response that did something starts with Ran Playwright code: the exact Playwright code the server ran
- The server turned the refs into normal locators, like
getByRole('button', { name: 'Add' }) browser_typeusedfill(). With"slowly": trueit types one key at a time instead- Actions like navigate and click also save a snapshot of the new page to a file in a
.playwright-mcpfolder
Because each step shows its code, the AI can collect these lines and write a normal Playwright test for you.
Useful Options
Add options after the command in the args list.
This configuration starts a headless Chromium browser that keeps nothing on disk:
Example
MCP configuration
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless", "--isolated"]
}
}
}
Headless means the browser runs without a visible window.
| Option | What it does |
|---|---|
| --headless | Runs the browser without a window. By default the window is visible |
| --browser <browser> | The browser to use: chrome, firefox, webkit or msedge |
| --isolated | Keeps the browser profile (cookies, logins, storage) in memory only. Nothing is saved when the browser closes |
| --device <device> | Emulates a device, for example "iPhone 15" (see Mobile) |
| --storage-state <path> | Starts an isolated browser with saved cookies and storage, for example a test user who is already logged in (see Authentication) |
| --allowed-origins <origins> | Only these origins (like https://www.w3schools.com) may be requested. Separate several with a semicolon |
| --blocked-origins <origins> | Requests to these origins are blocked |
| --caps vision | Adds mouse tools that click at x and y positions on a screenshot, for elements that are not in the snapshot |
To see all options, run:
Example
npx playwright mcp --help
Use It Safely
The AI works in a real browser.
A click on "Buy", "Delete" or "Send" really happens.
- Use a test website and a test account, not your real accounts
- Do not give the AI your real passwords. If it must log in, use a test user (the
--storage-stateoption can load a saved login) - Use
--isolated, so the browser does not keep cookies from one session to the next - Read what the AI wants to do before you allow a tool call. Most AI apps ask you first
- Be careful with
browser_run_code_unsafe. It runs any JavaScript code on your computer, inside the server, not only in the page. Only allow it when you have read the code - Web pages can contain text that tries to give the AI new orders. Treat what the AI reads on a page as data
Note: --allowed-origins and --blocked-origins are not a security boundary.
The help text says so, and they do not apply to redirects.
Use them to keep the AI on track, not to protect your system.
MCP or Tests?
MCP and Playwright tests do different jobs.
| Playwright MCP | Playwright tests |
|---|---|
| An AI decides each step while it works | The steps are written in a file |
| Good for exploring a page, checking a bug, or doing a task once | Good for checking the same things again and again |
| Can give a different result each time | Gives the same result each time, if the page does not change |
| Needs an AI app, and costs AI usage | Runs anywhere with npx playwright test, also in CI |
A good way to use both: let the AI explore with MCP, then ask it to write a test from what it did.
The "Ran Playwright code" lines give it the exact code to start from.
Then you review the test, run it, and keep it in your project.
Playwright also has ready-made AI agents that plan, write and fix tests.
They are the topic of the next chapter, Agents.