What is Playwright MCP server?

Playwright MCP (Model Context Protocol) server is an official Microsoft tool that allows AI assistants like Claude to control a browser using structured accessibility snapshots instead of screenshots. It provides reliable, fast browser automation for AI agents.

How to install Playwright MCP?

Run: npx @playwright/mcp@latest to start the server. For VS Code, add the configuration to your MCP settings file. The server uses the Playwright browser automation library under the hood.

Complete Guide & Cheatsheet

Playwright MCP

A Model Context Protocol server that gives AI agents full browser automation power — without screenshots, without vision models. Pure structured data, maximum reliability.

27k+ GitHub Stars@playwright/mcpNode.js 18+VS Code · Cursor · Claude

01What is Playwright MCP?

Understand the concept before diving into commands.

MCP stands for Model Context Protocol — an open standard that lets AI assistants (Copilot in VS Code, Claude, Cursor) control external tools.

Playwright MCP wraps the Playwright browser automation library into an MCP server. Instead of taking screenshots and asking a vision AI to guess what's on screen, it reads the page's accessibility tree — structured data describing every element. This is faster, cheaper, and more reliable.

AI Assistant (Copilot/Claude)→MCP Protocol→Playwright MCP Server→Real Browser (Chrome/Firefox)→Web Page

✓ What it's great for

• Automating web workflows with AI
• Form filling, data extraction
• End-to-end test generation
• Multi-step web navigation
• Long-running autonomous tasks

⚡ MCP vs CLI

• MCP = persistent browser state
• CLI = more token-efficient
• MCP = better for exploration
• CLI = better for bulk testing
• Use MCP for agentic loops

02Installation

You need Node.js 18 or newer. That's the only real prerequisite.

1
Check Node.js version
Open a terminal and verify you have Node.js 18+
```
node --version
# Expected: v18.x.x or higher
```
2
No global install needed!
Playwright MCP runs via npx — it downloads and runs automatically. You don't need to install it globally.
```
npx @playwright/mcp@latest --version
# This downloads and prints the version
```
3
Optional: Install browsers explicitly
If Chromium isn't installed, Playwright MCP will prompt you. You can pre-install it:
```
npx playwright install chromium
# Or install all browsers:
npx playwright install
```

💡

Pro tip: You never need to run the MCP server manually. VS Code (or any MCP client) will start and stop it automatically based on the config you add.

03VS Code Setup

The fastest path: add Playwright MCP to VS Code in under 2 minutes.

Method A — One Command (Fastest)

Run this in your terminal while VS Code is installed:

TERMINAL

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

That's it. Restart VS Code and the server is ready.

Method B — Manual Config File

1
Open the MCP config file
In VS Code: press Ctrl+Shift+P → search "MCP: Edit Server Configuration" Or create the file manually at .vscode/mcp.json in your project.

Paste the minimal config

.vscode/mcp.json

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

3
Save and verify
Press Ctrl+Shift+P → "MCP: List Servers". You should see playwright listed with a green status.

Method C — With Extra Options (Recommended for teams)

.vscode/mcp.json

{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser", "chromium",
        "--headless",
        "--output-dir", "./playwright-output",
        "--save-trace"
      ]
    }
  }
}

ℹ️

Note for GitHub Copilot users in VS Code: After adding the config, open Copilot Chat, switch to Agent mode (dropdown next to the input), and Playwright tools will appear automatically when you ask Copilot to browse something.

04Your First Run

Test that everything works end-to-end.

In VS Code Copilot Chat

Open Copilot Chat → switch to Agent mode → type:

PROMPT EXAMPLE

Go to https://example.com, take a screenshot, and tell me the page title.

Copilot will automatically use browser_navigate, then browser_snapshot or browser_take_screenshot.

Manual Server Test (Terminal)

TERMINAL

# Run the server directly to confirm it starts
npx @playwright/mcp@latest

# Or with a visible browser window (headed mode)
npx @playwright/mcp@latest --browser chromium

# Or as a standalone HTTP server on port 8931
npx @playwright/mcp@latest --port 8931

05CLI Arguments Reference

All arguments go in the args array of your config.

Browser Control

Argument	Values	Default	Description
--browser	chrome, firefox, webkit, msedge	chromium	Which browser engine to use
--headless	flag	headed	Run without visible window (great for CI)
--device	"iPhone 15", etc.	—	Emulate a mobile device
--viewport-size	"1280x720"	—	Set browser window size
--user-agent	string	—	Override the user agent string
--executable-path	path	—	Use a custom browser binary
--cdp-endpoint	URL	—	Connect to an existing browser via CDP

Session & Storage

Argument	Description
--isolated	Fresh browser profile every session (no cookies saved)
--user-data-dir <path>	Custom directory for browser profile (login state persists)
--storage-state <path>	Load saved cookies/localStorage (from Playwright auth)

Output & Debugging

Argument	Description
--output-dir <path>	Where to save screenshots, PDFs, traces
--save-trace	Save Playwright Trace Viewer file for debugging
--save-video <size>	Record a video of the session (e.g. 800x600)
--console-level <lvl>	error/warning/info/debug — which console messages to capture

Network & Security

Argument	Description
--proxy-server <url>	Route traffic through a proxy
--ignore-https-errors	Accept invalid/expired SSL certs
--blocked-origins <list>	Block specific origins from loading
--no-sandbox	Disable browser sandbox (Docker only)

Extra Capabilities

Argument	Description
--caps vision	Enable coordinate-based mouse tools (xy clicks, drags)
--caps pdf	Enable browser_pdf_save tool
--caps devtools	Enable DevTools access
--caps testing	Enable test assertion tools
--caps vision,pdf	Multiple caps comma-separated

Timing & Performance

Argument	Default	Description
--timeout-action <ms>	5000ms	Max time to wait for a single action
--timeout-navigation <ms>	60000ms	Max time to wait for page navigation
--snapshot-mode	incremental	incremental / full / none

06Config File

For complex setups, use a JSON config file instead of long argument lists.

playwright-mcp.config.json

{
  "browser": {
    "browserName": "chromium",
    "isolated": false,
    "userDataDir": "./browser-data",
    "launchOptions": {
      "headless": false,
      "channel": "chrome"
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 },
      "locale": "en-US",
      "timezoneId": "America/New_York"
    }
  },
  "server": { "port": 8931, "host": "localhost" },
  "capabilities": ["core", "pdf", "vision"],
  "outputDir": "./playwright-output",
  "saveTrace": true,
  "timeouts": { "action": 5000, "navigation": 30000 },
  "console": { "level": "info" },
  "network": { "blockedOrigins": ["https://ads.example.com"] }
}

Use it in your VS Code MCP config:

.vscode/mcp.json

{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--config", "./playwright-mcp.config.json"]
    }
  }
}

07Browser Profiles

Three modes for managing login state and sessions.

🔒 Persistent (Default)

args: ["@playwright/mcp@latest"]
# Profile stored at:
# macOS: ~/Library/Caches/ms-playwright/...

🧪 Isolated

Fresh profile every session. Perfect for testing where you need a clean slate.

args: [
  "@playwright/mcp@latest",
  "--isolated",
  "--storage-state=./auth.json"
]

🌐 Browser Extension Mode

Connect to your actual running Chrome/Edge with all your existing logins, extensions, and tabs.

args: ["@playwright/mcp@latest", "--extension"]
# Requires: "Playwright MCP Bridge" extension in Chrome/Edge

Saving & Reusing Auth State

save-auth.js (run once)

const { chromium } = require('playwright');
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://yoursite.com/login');
// ... fill in credentials manually ...
await page.context().storageState({ path: 'auth.json' });
await browser.close();

MCP config with saved auth

args: ["@playwright/mcp@latest", "--isolated", "--storage-state=auth.json"]

08Capabilities (Tool Groups)

Tools are grouped into capabilities. Most are active by default; some require opt-in.

Capability	Flag	Included Tools	When to use
core	always on	navigate, click, type, screenshot, snapshot, fill, wait…	Always available — standard automation
vision	--caps vision	mouse_click_xy, mouse_drag_xy, mouse_move_xy, mouse_wheel	When elements have no accessibility label (canvas, games)
pdf	--caps pdf	browser_pdf_save	Saving pages as PDFs
devtools	--caps devtools	DevTools integration	Advanced debugging scenarios
testing	--caps testing	generate_locator, verify_element_visible, verify_text_visible…	Writing or verifying automated tests

⚠️

Vision mode caveat: Coordinate-based tools (xy clicks) are fragile — if the layout changes by even a pixel, clicks will miss. Always prefer accessibility-based tools (browser_click with ref) when possible.

09Core Automation Tools

These tools are always available. Blue = read-only (observes page). Green = read-write (changes it).

🌐 Navigation

🔍 Observation

🖱️ Interaction

⏳ Waiting & Flow

10Tab Management

Manage multiple browser tabs in a single session.

11Vision Tools

Requires --caps vision. Coordinate-based mouse tools. Use only when accessibility-based tools don't work (canvas apps, games).

⚠️

These tools use pixel coordinates (x, y). They break if the layout shifts. Always prefer core tools with ref when available.

Tool	Parameters	Description
browser_mouse_click_xy	x, y (numbers)	Click at exact pixel position
browser_mouse_move_xy	x, y (numbers)	Move mouse to position (no click)
browser_mouse_down	button? (default left)	Press mouse button down (hold)
browser_mouse_up	button? (default left)	Release mouse button
browser_mouse_drag_xy	startX, startY, endX, endY	Click-drag from one coordinate to another
browser_mouse_wheel	deltaX, deltaY (numbers)	Scroll the mouse wheel

12PDF Tools

Requires --caps pdf.

13Testing Tools

Requires --caps testing.

Tool	Key Parameters	Description
browser_generate_locator	ref (required)	Generate a Playwright locator string for use in test code
browser_verify_element_visible	role, accessibleName	Assert an element with given role + name is visible. Throws if not.
browser_verify_text_visible	text	Assert specific text is visible on the page
browser_verify_list_visible	ref, items[]	Assert a list element contains the expected items
browser_verify_value	ref, value, type	Assert an input has a specific value (use "true"/"false" for checkboxes)

EXAMPLE TEST WORKFLOW

1. Navigate to the page
2. Fill the login form
3. Click submit
4. Use browser_verify_text_visible to check "Welcome back, John"
5. Use browser_generate_locator to get locator for the dashboard element
6. Copy the generated locator into your Playwright test file

14Real Workflow Examples

Complete end-to-end examples you can copy and adapt.

1. Scrape a table from a webpage

PROMPT TO AI

Go to https://example.com/prices, take a snapshot, find the pricing table, and return all the data in JSON format.

2. Fill and submit a form

PROMPT TO AI

Go to https://myapp.com/register and fill in the registration form:
- First name: Alice
- Last name: Smith
- Email: alice@example.com
- Password: MySecurePass123!
Then click the Register button and wait for the success message.

5. Debug a broken page

PROMPT TO AI

Go to https://myapp.com, open the console, look for any JavaScript errors, check network requests for any failed API calls, take a screenshot, and give me a report of what's broken.

3. Screenshot & Save PDF Report

CONFIG (.vscode/mcp.json)

{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--caps", "pdf", "--output-dir", "./reports", "--headless"]
    }
  }
}

PROMPT TO AI

Go to https://example.com/dashboard, wait for all charts to load, take a full-page screenshot saved as dashboard.png, then save a PDF as dashboard.pdf.

6. Authenticated session with saved state

STEP 1 — Save auth (run once)

npx playwright codegen --save-storage=auth.json https://myapp.com/login
# Log in manually in the opened browser, then close it
# auth.json now contains your cookies/localStorage

STEP 2 — MCP config using saved auth

{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--isolated", "--storage-state=auth.json"]
    }
  }
}

7. Run in Docker (CI/CD)

docker-compose.yml

services:
  playwright-mcp:
    image: mcr.microsoft.com/playwright/mcp
    entrypoint: node
    command: cli.js --headless --browser chromium --no-sandbox --port 8931
    ports:
      - "8931:8931"

MCP CLIENT CONFIG (CI environment)

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

15Best Practices

Always take a snapshot before interacting

✓ Good

1. browser_snapshot()
2. Find ref="e42" for Login
3. browser_click({ ref: "e42" })

✗ Bad

browser_click({ 
  element: "Login button" 
})
// Guessing — unreliable

Prefer browser_fill_form over multiple browser_type calls

✓ Efficient

browser_fill_form({
  fields: [
    { ref: "e10", value: "Alice" },
    { ref: "e11", value: "alice@x.com" }
  ]
})

✗ Slow

browser_type({ ref: "e10", text: "Alice" })
browser_type({ ref: "e11", text: "alice@x.com" })
// 2 separate tool calls

Additional Golden Rules

→Use --isolated for test automation so sessions don't bleed into each other
→Use browser_wait_for with text conditions, not fixed time delays when possible
→Use --no-sandbox only inside Docker containers — never in production systems
→Use --save-trace for debugging failed runs — open with npx playwright show-trace
→Use --blocked-origins to block analytics/ads and speed up page loading during automation

16Troubleshooting

Problem	Likely Cause	Fix
Browser not found error	Browsers not installed	Run: npx playwright install chromium
Timeout on navigation	Page too slow	Add --timeout-navigation 120000
Click fails / element not found	Stale ref — snapshot outdated	Always take a fresh snapshot before clicking
MCP server not showing in VS Code	Config syntax error	Validate JSON; check the file path
SSL certificate errors	Self-signed cert or corp proxy	Add --ignore-https-errors
Login state lost	Running in --isolated mode	Use --storage-state=auth.json or remove --isolated
Server starts but no tools appear	MCP client not in agent mode	In VS Code Copilot, switch chat to "Agent" mode
Docker container can't open browser	Missing --no-sandbox flag	Add --no-sandbox flag in Docker only

Quick Diagnostic Checklist

□node --version → 18.x or higher?
□npx @playwright/mcp@latest --version → runs without error?
□.vscode/mcp.json valid JSON?
□VS Code Copilot chat in "Agent" mode (not "Chat")?
□Playwright servers listed in Ctrl+Shift+P → "MCP: List Servers"?
□Browsers installed? Run: npx playwright install

17References & Official Docs

Always check the official sources for the latest updates.

📦 microsoft/playwright-mcp 📦 @playwright/mcp on npm 📚 Playwright Docs 🔗 MCP Protocol Spec 💻 VS Code MCP Guide