---
title: Set Up an Agent with Playwright MCP | TestingBot
description: In this chapter you give an AI agent a real browser. By the end, you
  can ask it in plain language to open a page, interact with it and report what it
  saw,…
source_url:
  html: https://testingbot.com/resources/courses/ai-test-automation/set-up-playwright-mcp
  md: https://testingbot.com/resources/courses/ai-test-automation/set-up-playwright-mcp.md
---

Course

[AI Test Automation: A Hands-On Course](https://testingbot.com/resources/courses/ai-test-automation)

Chapter 2 of 9

1. [1 AI Test Automation: A Hands-On Course](https://testingbot.com/resources/courses/ai-test-automation)
2. [2 Set Up an Agent with Playwright MCP](https://testingbot.com/resources/courses/ai-test-automation/set-up-playwright-mcp)
3. [3 From Test Plan to Playwright Test with an Agent](https://testingbot.com/resources/courses/ai-test-automation/generate-tests-from-a-plan)
4. [4 Playwright Test Agents: Planner, Generator and Healer](https://testingbot.com/resources/courses/ai-test-automation/playwright-test-agents)
5. [5 Self-Healing Tests: When Healing Hides a Regression](https://testingbot.com/resources/courses/ai-test-automation/self-healing-tests)
6. [6 AI for Failure Triage: Traces, Logs and Privacy](https://testingbot.com/resources/courses/ai-test-automation/ai-failure-triage)
7. [7 Run AI-Written Suites on TestingBot](https://testingbot.com/resources/courses/ai-test-automation/run-on-testingbot)
8. [8 Guardrails for AI in a Test Suite](https://testingbot.com/resources/courses/ai-test-automation/guardrails)
9. [9 AI Test Automation Quiz](https://testingbot.com/resources/courses/ai-test-automation/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 2 of 9 Intermediate 7 min read 2 quick checks Updated Nov 2026 

# Set Up an Agent with Playwright MCP
On this page
1. [What MCP is, in one paragraph](https://testingbot.com#what-mcp-is-in-one-paragraph)
2. [Install it in your client](https://testingbot.com#install-it-in-your-client)
3. [Drive the browser](https://testingbot.com#drive-the-browser)
4. [Options worth knowing](https://testingbot.com#options-worth-knowing)
5. [The non-AI baseline: codegen](https://testingbot.com#the-non-ai-baseline-codegen)

In this chapter you give an AI agent a real browser. By the end, you can ask it in plain language to open a page, interact with it and report what it saw, and you will know what the agent actually receives from the browser. That knowledge explains most of what goes right and wrong in later chapters.

## What MCP is, in one paragraph[#](https://testingbot.com#what-mcp-is-in-one-paragraph)

The Model Context Protocol is a standard way for an AI client (Claude Code, VS Code with GitHub Copilot, Cursor, Claude Desktop and others) to call tools provided by a separate program, the **MCP server**. The server describes its tools and their parameters; the model decides when to call them; the client runs the call and returns the result to the model. Playwright MCP is an MCP server from the Playwright team that exposes a browser as tools: `browser_navigate`, `browser_click`, `browser_type`, `browser_snapshot`, `browser_take_screenshot` and more.

The model never touches the browser directly. It only sees what the tools return, so the quality of that output sets the ceiling on everything the agent does.

## Install it in your client[#](https://testingbot.com#install-it-in-your-client)

Playwright MCP runs through `npx`, so there is nothing to install globally. You need Node.js 20 or newer.

**Claude Code:**

```bash
claude mcp add playwright -- npx @playwright/mcp@0.0.85
```

**VS Code** (GitHub Copilot agent mode), from a terminal:

```bash
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@0.0.85"]}'
```

**Any other MCP client** takes the same command in its JSON config, usually under `mcpServers`:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@0.0.85"]
    }
  }
}
```

The official README uses `@playwright/mcp@latest`. We pin an exact version instead, for the same reason you pin `@playwright/test`: the tool names, the snapshot format and the default behaviour change between releases, and a silent change in what the agent sees is painful to debug. Bump the version deliberately, like any other dependency.

The first time the server starts a browser it may need to download one. If it reports a missing browser, run `npx @playwright/mcp@0.0.85 install-browser chrome` or point it at an installed Chrome with `--browser chrome`.

We ran the Claude Code variant for this course. The VS Code command is from the Playwright MCP README and was not run here.

## Drive the browser[#](https://testingbot.com#drive-the-browser)

Start your client in an empty folder and ask:

> Open [https://demo.playwright.dev/todomvc/](https://demo.playwright.dev/todomvc/), add a todo "Buy milk", and tell me what the page shows afterwards.

The agent calls `browser_navigate`, then `browser_type` with `submit: true`, then `browser_snapshot`. Each tool result has two parts worth understanding. First, the Playwright code that the tool ran:

```javascript
await page.getByPlaceholder('What needs to be done?').fill('Buy milk');
await page.getByPlaceholder('What needs to be done?').press('Enter');
```

Second, an **accessibility snapshot** of the page: a YAML tree of roles, accessible names and states, with a reference (`ref`) on every element the agent can act on. This is an excerpt of the snapshot from our run:

```yaml
- textbox "What needs to be done?" [active] [ref=f10e8]
- list [ref=f10e18]:
  - listitem [ref=f10e19]:
    - generic [ref=f10e20]:
      - checkbox "Toggle Todo" [ref=f10e21]
      - generic [ref=f10e22]: Buy milk
- generic [ref=f10e24]:
  - strong [ref=f10e25]: "1"
  - text: item left
- link "Active" [ref=f10e30] [cursor=pointer]:
  - /url: "#/active"
```

Three consequences follow from this format:

- **The agent sees roles and names, not pixels.** It knows there is a checkbox called "Toggle Todo" and a link called "Active", which is exactly the information Playwright's `getByRole` locators use. That is why tests generated through MCP tend to have good locators.
- **It sees only what the page exposes.** An icon-only button with no accessible name shows up as `button [ref=...]` with nothing to tell it apart. The agent will then guess, use position, or ask for a screenshot. Poor accessibility makes your app harder to test for agents as well as for people.
- **The snapshot is a moment in time.** If content arrives 300 ms after a click, a snapshot taken immediately does not contain it. Agents mostly cope by taking another snapshot, but the generated test still has to wait properly (chapter 2).

Screenshots are available (`browser_take_screenshot`), and the `--caps vision` option adds coordinate-based tools for canvas-heavy pages. Snapshots are the default because text is cheaper for the model to read and more precise to act on.

An agent driving your app through Playwright MCP keeps clicking the wrong one of three identical-looking icon buttons. What is the most likely cause?

 The model is too small and needs to be swapped for a larger one The buttons have no accessible names, so they look identical in the snapshot Playwright MCP does not support buttons inside toolbars The page loads too slowly for the snapshot

The agent reads the accessibility tree. Three buttons without an `aria-label` or visible text show up as three unnamed buttons, so any model has to guess. Naming them fixes it for agents, for your tests and for screen-reader users.

## Options worth knowing[#](https://testingbot.com#options-worth-knowing)

Add these to the `args` array after the package name:

- `--headless`: no visible window. Headed is the default on a desktop, and it is worth keeping while you learn, because watching the agent work is the fastest way to see where it goes wrong.
- `--isolated`: keep the browser profile in memory, so every session starts logged out with no cookies. Without it, Playwright MCP keeps a persistent profile, and the agent can pick up a login from yesterday.
- `--browser firefox` (or `webkit`, `msedge`, `chrome`): which browser to drive.
- `--storage-state auth.json`: start an isolated session with a saved login, the same file format Playwright Test uses.
- `--secrets .env.mcp`: a dotenv file of secret values. When a tool result contains one of those values, the server replaces it with a placeholder before the model sees it. The README calls this a convenience, not a security feature, and it is right: it stops accidental leaks, not a determined page or prompt.
- `--allowed-origins`: limit which origins the browser may request. Also not a security boundary, according to the same README, but useful for keeping an agent on your staging site.
- `--output-dir`: where snapshots, console logs and screenshots go. By default the server writes them under `.playwright-mcp/` in the working directory, so add that folder to `.gitignore`.

The Playwright MCP README states that the server "is **not** a security boundary". Treat the agent's browser like any other automation with access to your accounts: test environments, test users, no production admin sessions. Chapter 7 returns to this.

## The non-AI baseline: codegen[#](https://testingbot.com#the-non-ai-baseline-codegen)

Before relying on an agent to write tests, compare it with what Playwright already gives you for free:

```bash
npx playwright codegen https://demo.playwright.dev/todomvc/
```

Codegen records your clicks and typing into test code, choosing role-based locators the same way MCP does. It costs nothing per run, is deterministic, and has a button for adding assertions. What it cannot do is decide what to do next, read a test plan, or explore a page you have not seen. Keep both: codegen when you know the steps, an agent when you want something to work out the steps, or to do the typing for twenty scenarios.

You started Playwright MCP with `--secrets .env.mcp` containing your staging password. Which statement is accurate?

 Matching values in tool output are replaced before the model sees them, but this is a convenience and not a security boundary The password is now encrypted end to end and can never reach the model provider The agent can no longer type the password into a login form

The secrets file masks exact matches in what the server returns. Anything that reaches the model another way (a prompt, a file the agent reads, a value the page transforms) is not covered. The README says the same, so use test credentials.

You now have an agent that can drive a browser and a clear picture of what it sees. Next, you make it write tests, and learn the checklist that decides whether those tests are allowed in.

[Previous · Chapter 1 AI Test Automation: A Hands-On Course](https://testingbot.com/resources/courses/ai-test-automation) [Next · Chapter 3 From Test Plan to Playwright Test with an Agent](https://testingbot.com/resources/courses/ai-test-automation/generate-tests-from-a-plan)

On this page

1. [What MCP is, in one paragraph](https://testingbot.com#what-mcp-is-in-one-paragraph)
2. [Install it in your client](https://testingbot.com#install-it-in-your-client)
3. [Drive the browser](https://testingbot.com#drive-the-browser)
4. [Options worth knowing](https://testingbot.com#options-worth-knowing)
5. [The non-AI baseline: codegen](https://testingbot.com#the-non-ai-baseline-codegen)

Certification

This course has a free, hands-on certificate.

[How it works](https://testingbot.com/resources/courses/ai-test-automation/certification)