Playwright MCP: Browser Automation with AI Agents (Setup and Examples)

Playwright MCP gives AI assistants a real browser they can drive with Playwright. In this lesson you will understand how it works, install it in popular AI clients, learn its tools and options, and use it for exploration, test drafting and debugging.

---

🤖 What Is Playwright MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants use external tools. Playwright MCP (@playwright/mcp) is Microsoft’s MCP server that gives an AI assistant, such as Claude, GitHub Copilot in VS Code or Cursor, a real browser it can control through Playwright.

With it, you can ask an assistant in plain English:

• “Open the Sauce Demo site, log in as standard_user and tell me what is on the products page.”
• “Check whether the checkout form shows an error when the postcode is empty.”
• “Explore this page and write a Playwright TypeScript test for adding two items to the cart.”

The assistant then navigates, clicks, types and reads the page step by step, using Playwright under the hood.

New to AI agents? Read Fundamentals of Agentic AI for Beginners first.

---

🧠 How It Works: Accessibility Snapshots, Not Screenshots

By default, Playwright MCP does not send screenshots to the AI. It sends an accessibility snapshot: a structured, text-based view of the page with roles, names and references for each element, the same information behind getByRole locators.

Approach	Playwright MCP default	Screenshot-based agents
Input to the AI	Structured accessibility tree (text)	Pixels
Speed and cost	Fast, small	Slower, larger
Precision	Acts on exact elements	Guesses coordinates
Needs a vision model	No	Yes

Screenshots are still available as a separate tool when the assistant needs to “see” the page.

---

⚙️ Install Playwright MCP

You need Node.js (see Install Playwright) and an MCP-capable AI client.

Standard configuration (most clients)

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Claude Code

claude mcp add playwright npx @playwright/mcp@latest

VS Code (GitHub Copilot agent mode)

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

Cursor

Open Cursor Settings, MCP, Add new MCP Server, choose the command type and enter npx @playwright/mcp@latest.

After installing, restart the client and check that the Playwright tools are listed and enabled.

---

🧰 The Tools the AI Gets

The server exposes browser actions as tools. The most important ones:

Tool	What the AI can do
browser_navigate, browser_navigate_back	Open URLs, go back
browser_snapshot	Read the page as an accessibility snapshot
browser_click, browser_hover, browser_drag	Mouse interactions
browser_type, browser_fill_form, browser_press_key	Typing and keyboard
browser_select_option, browser_file_upload	Dropdowns and uploads
browser_handle_dialog	Accept or dismiss alerts
browser_wait_for	Wait for text to appear or disappear
browser_tabs	List, open, switch and close tabs
browser_take_screenshot	Capture an image when visual context is needed
browser_console_messages, browser_network_requests	Read console logs and network traffic
browser_evaluate	Run JavaScript on the page
browser_close, browser_resize	Manage the browser window

---

🎛️ Useful Options

Add options to the args array in the configuration:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chrome", "--isolated", "--device", "iPhone 15"]
    }
  }
}

Option	Purpose
--headless	Run without a visible window (headed is the default)
--browser	chrome, firefox, webkit or msedge
--isolated	Keep the browser profile in memory; nothing is saved between sessions
--user-data-dir	Use a persistent profile folder
--storage-state	Start an isolated session with saved cookies and storage (login sessions)
--device	Emulate a device such as "iPhone 15" (mobile emulation)
--caps	Enable extra capabilities: vision, pdf, devtools
--output-dir	Folder for screenshots and other output files

---

🧪 Practical Workflows for Testers

1. Exploratory testing assistant

💬 “Using the Playwright tools, open https://www.saucedemo.com, log in as standard_user with password secret_sauce, sort products by price high to low, and report the first three products and their prices.”

The assistant performs the steps and reports what it saw, which is useful for quick checks and reproducing bugs.

2. Generate a first draft of a test

💬 “Explore the checkout flow on Sauce Demo with the browser, then write a Playwright Test in TypeScript that adds the backpack, checks out with test data, and asserts the order confirmation. Use getByRole and data-test locators.”

Because the assistant has seen the real page, its locators are usually accurate. Treat the result like Codegen output: review it, add assertions and move it into your framework structure.

3. Debug a failing test

💬 “This test fails at the checkout button. Open the page, take a snapshot at that step, and explain why the button cannot be clicked.”

The assistant can read console errors and network requests to suggest causes.

---

⚠️ Safety and Good Practice

• Use test environments and test accounts. The AI acts with whatever access the browser has.
• Prefer --isolated so sessions do not reuse real cookies or logins.
• Review every action your client asks to approve, especially form submissions.
• Do not share secrets in prompts; use --storage-state with a test session instead.
• Keep humans in charge of assertions. The AI can draft tests, but you decide what “correct” means.

---

🔄 Playwright MCP vs Playwright Test Agents

	Playwright MCP	Playwright Test Agents
What it is	An MCP server giving any AI client browser control	Ready-made planner, generator and healer agents for Playwright Test
Best for	Exploration, ad-hoc tasks, drafting tests, debugging	A structured loop: plan, generate and heal a test suite
Output	Whatever you ask for	Markdown test plans and Playwright test files

---

📝 Assignment

1. Install Playwright MCP in your AI client (Claude Code, VS Code or Cursor) and confirm the tools are listed.
2. Ask the assistant to open https://www.saucedemo.com and describe the login page using a snapshot.
3. Ask it to log in, add two products to the cart and report the cart badge number.
4. Ask it to write a Playwright TypeScript test for that flow, then run the test locally and fix anything that fails.
5. Restart the server with --isolated --device "iPhone 15" and repeat task 2. What changed?
6. Bonus: compare the AI-generated test with your own test from your first Playwright test. Which locators and assertions are better?

---

❓ FAQ

🤔 What is Playwright MCP?

An MCP server from Microsoft (@playwright/mcp) that lets AI assistants control a real browser through Playwright, using accessibility snapshots to understand the page.

🤔 How do I install Playwright MCP in Claude Code?

Run claude mcp add playwright npx @playwright/mcp@latest, then restart Claude Code.

🤔 Does Playwright MCP use screenshots?

Not by default. It uses accessibility snapshots, which are faster and more precise. A screenshot tool is available when visual context is needed.

🤔 Can Playwright MCP replace my test suite?

No. It is excellent for exploration, drafting and debugging, but a reliable regression suite still needs reviewed, deterministic Playwright tests running in CI.

🤔 Which browsers does Playwright MCP support?

Chrome, Firefox, WebKit and Microsoft Edge, selected with the --browser option.

---

🎯 Next Steps

• 🎭 Playwright Test Agents: Planner, Generator, Healer
• 🤖 AI Tools for QA Engineers
• 💼 AI + QA Automation Interview Questions
• 🎭 Playwright Tutorial with TypeScript