Menu
×
   ❮   
HTML CSS JAVASCRIPT SQL PYTHON JAVA PHP C C++ C# AWS W3.CSS HOW TO BOOTSTRAP REACT MYSQL JQUERY EXCEL XML DJANGO NUMPY PANDAS NODEJS DSA TYPESCRIPT ANGULAR ANGULARJS GIT POSTGRESQL MONGODB ASP AI R GO KOTLIN SWIFT SASS VUE GEN AI SCIPY CYBERSECURITY DATA SCIENCE INTRO TO PROGRAMMING HTML & CSS BASH RUST TOOLS MATH

Playwright MCP


Share

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:

ToolWhat it does
browser_navigateOpens a URL
browser_snapshotReturns the accessibility snapshot of the page
browser_clickClicks an element (by its ref)
browser_typeTypes text into an element, and can press Enter after it
browser_fill_formFills several form fields in one call (text boxes, checkboxes, radio buttons, selects)
browser_select_optionSelects an option in a drop-down list
browser_press_keyPresses a key, like Enter or Escape
browser_wait_forWaits for a text to appear or disappear, or for a number of seconds
browser_take_screenshotTakes a screenshot of the page or of one element
browser_tabsLists, opens, closes or selects browser tabs
browser_console_messagesReturns the messages the page wrote to the browser console
browser_network_requestsLists the network requests the page sent
browser_navigate_backGoes back to the previous page
browser_closeCloses 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

  • target is the ref from the snapshot
  • element is 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_type used fill(). With "slowly": true it 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-mcp folder

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.

OptionWhat it does
--headlessRuns the browser without a window. By default the window is visible
--browser <browser>The browser to use: chrome, firefox, webkit or msedge
--isolatedKeeps 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 visionAdds 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-state option 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 MCPPlaywright tests
An AI decides each step while it worksThe steps are written in a file
Good for exploring a page, checking a bug, or doing a task onceGood for checking the same things again and again
Can give a different result each timeGives the same result each time, if the page does not change
Needs an AI app, and costs AI usageRuns 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.



Free account

Track your progress

XP earned 0 Day streak 0 Spaces 0 League —

New

Learn in Adventure Mode W3Schools Adventure App

Coding fundamentals as bite-sized lessons and challenges.

×

Contact Sales

If you want to use W3Schools services as an educational institution, team or enterprise, send us an e-mail:
sales@w3schools.com

Report Error

If you want to report an error, or if you want to make a suggestion, send us an e-mail:
help@w3schools.com

W3Schools is optimized for learning and training. Examples might be simplified to improve reading and learning. Tutorials, references, and examples are constantly reviewed to avoid errors, but we cannot warrant full correctness of all content. While using W3Schools, you agree to have read and accepted our terms of use, cookies and privacy policy.

Copyright 1999-2026 by Refsnes Data. All Rights Reserved. W3Schools is Powered by W3.CSS.