Playwright MCP Server: AI-Powered Browser Automation Guide

TL;DR - Playwright MCP Quick Start

#2 most downloaded MCP server - Give your AI full browser control.

🆕 2025: Playwright MCP launched officially in March 2025, enabling AI agents like GitHub Copilot and Claude to control browsers via the accessibility tree! For an introduction to MCP, see the MCP Introduction guide.

Quick Setup:

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

What you can do:

• 🌐 Navigate: Go to any URL, handle redirects
• 🖱️ Interact: Click buttons, fill forms, select dropdowns
• 📸 Capture: Take screenshots, get page content
• 🔍 Extract: Scrape text, tables, structured data
• 🧪 Test: Run E2E tests with natural language

Example conversation:

You: Go to amazon.com, search for "wireless headphones", and tell me 
     the price of the first 3 results

Claude: I'll navigate to Amazon and search for you...
        
        Found top 3 results:
        1. Sony WH-1000XM5 - $348.00
        2. Bose QuietComfort - $249.00  
        3. Apple AirPods Max - $449.00

💡 Full guide below with all tools, accessibility snapshots, and automation workflows.

🤖 AI Integration: Playwright MCP works with GitHub Copilot, Claude, and other LLMs for natural language test automation.

Why Playwright MCP?

Playwright MCP transforms how AI interacts with the web:

Playwright vs Other Web MCPs

Choose Playwright when:

• The site uses JavaScript/React/Vue/Angular
• You need to fill forms or click buttons
• You want screenshots
• You’re testing your own application
• You want AI-assisted E2E testing

For more on AI-powered coding tools, see the AI-Powered IDEs Comparison guide.

2025 AI Features

Installation & Configuration

Prerequisites

• Node.js v18+ (check with node --version)
• MCP-compatible client (Claude Desktop, Cursor, etc.)

Claude Desktop Setup

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Cursor Setup

Add to your Cursor MCP settings:

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

Configuration Options

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {
        "PLAYWRIGHT_HEADLESS": "true",
        "PLAYWRIGHT_TIMEOUT": "30000",
        "PLAYWRIGHT_BROWSER": "chromium"
      }
    }
  }
}

Browser options: chromium, firefox, webkit

Visible Browser Mode

For debugging or watching the automation:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {
        "PLAYWRIGHT_HEADLESS": "false"
      }
    }
  }
}

Verify Installation

Restart your AI client and test:

You: Navigate to example.com and describe what you see

Claude: I've navigated to example.com. The page contains:
        - A heading "Example Domain"
        - Paragraph text explaining this is an example site
        - A link to "More information" pointing to IANA

Available Tools

Playwright MCP provides comprehensive browser control:

Navigation Tools

Interaction Tools

Content Tools

Wait Tools

Tab Management

Accessibility Snapshots: How AI “Sees” Pages

This is one of the most important concepts in Playwright MCP.

What Are Accessibility Snapshots?

Instead of processing images, Playwright MCP gives AI a structured representation of the page based on the accessibility tree:

Typical accessibility snapshot:

[document] Example Website
├── [navigation]
│   ├── [link] "Home"
│   ├── [link] "Products" 
│   └── [link] "Contact"
├── [main]
│   ├── [heading level=1] "Welcome"
│   ├── [paragraph] "Lorem ipsum..."
│   ├── [button] "Get Started"
│   └── [textbox name="email"] placeholder="Enter email"
└── [footer]
    └── [link] "Privacy Policy"

Why This Works

Getting a Snapshot

You: Get the accessibility snapshot of this page

Claude: Here's the page structure:
        
        [document] GitHub - Login
        ├── [navigation]
        │   ├── [link] "GitHub"
        │   └── [link] "Sign up"
        ├── [main]
        │   ├── [heading level=1] "Sign in to GitHub"
        │   ├── [textbox name="Username or email"] 
        │   ├── [textbox name="Password" type="password"]
        │   ├── [link] "Forgot password?"
        │   └── [button] "Sign in"
        └── [footer]
            └── [link] "Terms" ...

Using Snapshots for Reliable Automation

You: Log me into the site
     Username: alice@example.com
     Password: ********

Claude: I'll use the form elements from the snapshot...
        1. Found textbox "Username or email" - filling with alice@example.com
        2. Found textbox "Password" - filling securely
        3. Found button "Sign in" - clicking
        
        Login submitted successfully! Page now shows the dashboard.

Web Scraping Workflows

Workflow 1: E-commerce Price Comparison

You: Go to amazon.com, search for "mechanical keyboard", and extract 
     the name, price, and rating of the top 5 results

Claude: I'll navigate and search...

        1. Navigated to amazon.com
        2. Found search box, entering "mechanical keyboard"
        3. Pressed Enter to search
        4. Waiting for results...
        5. Extracting product information...

        **Top 5 Results:**
        
        | Product | Price | Rating |
        |---------|-------|--------|
        | Logitech G Pro X | $149.99 | 4.6⭐ |
        | Keychron K8 | $89.99 | 4.5⭐ |
        | Razer Huntsman Mini | $119.99 | 4.4⭐ |
        | SteelSeries Apex Pro | $179.99 | 4.5⭐ |
        | Corsair K70 RGB | $139.99 | 4.7⭐ |

Workflow 2: News Headlines Aggregation

You: Go to news.ycombinator.com and list the current top 10 stories 
     with their points

Claude: Navigating to Hacker News...

        **Top 10 Stories:**
        
        1. [523 points] "OpenAI announces GPT-5" 
        2. [412 points] "The hidden costs of cloud computing"
        3. [389 points] "Show HN: I built a tool for..."
        ...

Workflow 3: Form-Based Data Retrieval

You: Go to a weather site, enter "New York" in the search, 
     and get the 5-day forecast

Claude: I'll fetch the forecast...

        1. Navigated to weather.com
        2. Found search input, entering "New York"
        3. Selected "New York, NY" from suggestions
        4. Extracting forecast data...

        **5-Day Forecast for New York, NY:**
        
        | Day | High | Low | Condition |
        |-----|------|-----|-----------|
        | Today | 45°F | 32°F | Cloudy |
        | Tue | 48°F | 35°F | Sunny |
        | Wed | 52°F | 38°F | Partly Cloudy |
        | Thu | 50°F | 36°F | Rainy |
        | Fri | 47°F | 33°F | Sunny |

Automated Testing Workflows

Workflow 1: Login Flow Testing

For more on AI-assisted development workflows, see the Building Your First AI Application guide.

You: Test the login flow on my-app.example.com:
     1. Try logging in with invalid credentials
     2. Verify error message appears
     3. Try with valid test credentials
     4. Verify dashboard loads

Claude: Running login flow tests...

        **Test 1: Invalid Credentials**
        - Navigated to my-app.example.com/login
        - Entered: invalid@test.com / wrongpassword
        - Clicked "Sign In"
        - ✅ PASS: Error message "Invalid credentials" appeared
        
        **Test 2: Valid Credentials**  
        - Entered: test@example.com / Test123!
        - Clicked "Sign In"
        - ✅ PASS: Redirected to /dashboard
        - ✅ PASS: "Welcome, Test User" heading visible
        
        **Summary: 2/2 tests passed**

Workflow 2: Form Validation Testing

You: Test the signup form validation on my-app.example.com/signup:
     - Submit empty form
     - Enter invalid email format
     - Enter mismatched passwords
     - Enter valid data

Claude: Testing signup form validation...

        **Test 1: Empty Form Submission**
        - Clicked "Create Account" with empty fields
        - ✅ PASS: "Email is required" error shown
        - ✅ PASS: "Password is required" error shown
        
        **Test 2: Invalid Email**
        - Entered "notanemail" in email field
        - ✅ PASS: "Please enter a valid email" error shown
        
        **Test 3: Password Mismatch**
        - Password: "Test123!"
        - Confirm Password: "Test456!"
        - ✅ PASS: "Passwords do not match" error shown
        
        **Test 4: Valid Submission**
        - Entered valid email and matching passwords
        - ✅ PASS: Successfully created account
        
        **Summary: 4/4 validation tests passed**

Workflow 3: Cross-Browser Testing

You: Test the checkout flow on both Chromium and Firefox

Claude: I'll test on both browsers...

        **Chromium Results:**
        - ✅ Add to cart works
        - ✅ Cart shows correct items
        - ✅ Checkout form renders properly
        - ✅ Payment form accessible
        
        **Firefox Results:**
        - ✅ Add to cart works
        - ✅ Cart shows correct items
        - ⚠️ Checkout button misaligned (CSS issue)
        - ✅ Payment form accessible
        
        **Issue Found:** 
        CSS rendering difference in Firefox for checkout button.
        Recommend checking flexbox compatibility.

Form Filling Automation

Single Form Filling

You: Go to the contact form on my-company.com/contact and fill it:
     Name: John Smith
     Email: john@example.com
     Subject: Product Inquiry
     Message: I'm interested in your enterprise plan. Please contact me.

Claude: Filling out the contact form...

        1. Navigated to my-company.com/contact
        2. Found form fields via accessibility snapshot
        3. Filled "Name" with "John Smith"
        4. Filled "Email" with "john@example.com"
        5. Selected "Product Inquiry" from Subject dropdown
        6. Filled message textarea
        7. Clicked "Submit"
        
        ✅ Form submitted successfully!
        Confirmation message: "Thank you for your inquiry. We'll be in touch."

Complex Multi-Step Forms

You: Complete the job application on careers.example.com:
     - Personal info: John Doe, john@email.com, (555) 123-4567
     - Position: Senior Developer
     - Experience: 5 years
     - Skip optional cover letter
     - Submit

Claude: Completing multi-step application...

        **Step 1: Personal Information**
        - Filled Name, Email, Phone
        - Clicked "Next"
        
        **Step 2: Position Details**
        - Selected "Senior Developer" from dropdown
        - Entered "5" in years of experience
        - Clicked "Next"
        
        **Step 3: Additional Documents**
        - Cover letter marked as optional
        - Skipping as requested
        - Clicked "Submit Application"
        
        ✅ Application submitted!
        Confirmation #: APP-2024-12345

Multi-Page Workflows

Handling Authentication Flows

You: Log into my dashboard at app.example.com, 
     go to Settings > Security,
     and enable two-factor authentication

Claude: I'll help you enable 2FA...

        1. **Login**
           - Navigated to app.example.com
           - Entered credentials
           - Logged in successfully
        
        2. **Navigation**
           - Clicked user menu
           - Clicked "Settings"
           - Clicked "Security" tab
        
        3. **Enable 2FA**
           - Found "Two-Factor Authentication" section
           - Clicked "Enable"
           - QR code displayed on screen
           
        📷 I've taken a screenshot of the QR code.
        
        Please scan this with your authenticator app, 
        then tell me the 6-digit code to complete setup.

Shopping Cart Workflow

You: On shop.example.com:
     1. Search for "running shoes"
     2. Add the first Nike result to cart
     3. Apply coupon code SAVE20
     4. Tell me the total

Claude: Shopping workflow in progress...

        1. **Search**
           - Entered "running shoes" in search
           - Found 24 results
        
        2. **Product Selection**
           - Filtered by brand: Nike
           - First result: Nike Air Zoom Pegasus - $129.99
           - Added to cart ✅
        
        3. **Apply Coupon**
           - Navigated to cart
           - Entered coupon: SAVE20
           - Applied successfully ✅
           - Discount: -$26.00
        
        **Cart Summary:**
        - Subtotal: $129.99
        - Discount: -$26.00
        - Total: $103.99

Example Prompts

Navigation & Basic Interaction

# Simple navigation
"Go to wikipedia.org"
"Navigate to https://docs.example.com/api"
"Open github.com/trending in the browser"

# Page interaction
"Click the Sign Up button"
"Type 'machine learning' in the search box and press Enter"
"Select 'English' from the language dropdown"
"Scroll down to the footer"
"Hover over the Products menu to see the dropdown"

Data Extraction

# Text extraction
"Get all the text from this article"
"Extract the main content, excluding navigation and ads"
"List all the links on this page with their URLs"

# Structured data
"Create a table of all products showing name, price, and availability"
"Extract the FAQ questions and answers as a list"
"Get all the review comments and their star ratings"

# Screenshots
"Take a screenshot of the full page"
"Screenshot just the main content area"
"Capture the error message that appeared"

Testing Prompts

# Functional testing
"Test if the login form accepts valid credentials"
"Verify that clicking 'Add to Cart' increases the cart count"
"Check if the search returns relevant results"

# Accessibility testing
"Check if all images have alt text"
"Verify the page works with keyboard navigation only"
"Test if form labels are properly associated with inputs"

# Visual testing
"Take a screenshot of the homepage for comparison"
"Check if the header is visible when scrolling down"
"Verify the mobile menu appears at narrow viewport"

Automation Prompts

# Data entry
"Fill out the registration form with test data"
"Submit a support ticket describing a billing issue"
"Book an appointment for next Tuesday at 2 PM"

# Multi-step processes
"Complete the checkout process using test payment details"
"Create a new project and add three team members"
"Export the monthly report as PDF"

# Monitoring
"Check if the API status page shows all services up"
"Verify the latest blog post was published today"
"Monitor the stock price display for changes"

Troubleshooting

Issue: “Element not found”

Symptoms: AI can’t find a button or input

Solutions:

You: Wait for the submit button to appear, then click it

Claude: Waiting for submit button...
        Found button after 1.2 seconds
        Clicked successfully ✅

Issue: “Page timeout”

Symptoms: Page takes too long to load

Solutions:

{
  "env": {
    "PLAYWRIGHT_TIMEOUT": "60000"
  }
}

Or in conversation:

You: Navigate to the page and wait up to 60 seconds for it to load

Issue: “CAPTCHA blocking”

Symptoms: Site shows CAPTCHA

Solutions:

1. Use PLAYWRIGHT_HEADLESS=false and solve manually
2. For your own sites: use test environments without CAPTCHA
3. Consider if the site’s ToS allows automation

Issue: “Authentication expires”

Symptoms: Logged out mid-session

Solutions:

You: If you get logged out, log back in using these credentials 
     and continue from where you left off

Issue: “Different browser behavior”

Symptoms: Works in Chrome but not Firefox

Solutions:

{
  "env": {
    "PLAYWRIGHT_BROWSER": "firefox"
  }
}

Best Practices

Do’s ✅

Don’ts ❌

For more on responsible AI tool usage, see the Understanding AI Safety, Ethics, and Limitations guide. | Run at maximum speed | Looks like attack |

Performance Tips

# Be specific about what you need
✅ "Extract just the product prices" 
❌ "Get everything from the page"

# Wait efficiently
✅ "Wait for the price to appear"
❌ "Wait 10 seconds"

# Handle errors gracefully
✅ "If the button isn't there, tell me what you see instead"
❌ "Click the button" (fails silently)

Security Considerations

Safe Operations

Credential Handling

# Safe: Have user enter credentials
You: Go to the login page
Claude: I'm on the login page. Please enter your credentials:
You: username: alice, password: ****

# Safer: Use test accounts
You: Log in using the test account credentials from our env variables

Site Permissions

Always check:

1. robots.txt: Does it allow automation?
2. Terms of Service: Is automation permitted?
3. Rate limits: What’s acceptable request frequency?

Combining with Other MCPs

Playwright + Filesystem

Save scraped data to files:

You: Scrape the product catalog from shop.example.com 
     and save it to products.json in my project folder

Claude: [Uses Playwright to scrape]
        [Uses Filesystem to save]
        
        Saved 127 products to /projects/data/products.json

Playwright + GitHub

Create issues from bug testing:

You: Test the checkout flow and create GitHub issues for any bugs found

Claude: [Uses Playwright to test]
        [Uses GitHub to create issues]
        
        Found 2 bugs:
        - Created Issue #45: "Checkout button unresponsive on mobile"
        - Created Issue #46: "Price calculation error with discount codes"

Playwright + Memory

Remember test results across sessions:

You: Run the E2E test suite and save results to memory

Claude: [Runs tests]
        [Saves to memory]
        
        Test results saved. You can ask about previous test runs anytime.

Related Articles

Summary

Playwright MCP Server gives AI assistants full browser control:

• ✅ Full browser automation with Chromium/Firefox/WebKit
• ✅ Accessibility snapshots for reliable element targeting
• ✅ All interactions: click, type, select, hover, scroll
• ✅ Screenshots for visual verification
• ✅ Multi-page flows for complex automations
• ✅ AI-assisted testing with GitHub Copilot integration (2025)

2025 Features:

• locator.describe() - AI-friendly element descriptions
• Copy as Prompt - Export locators for LLM use
• Speedboard - Identify slow tests (Playwright 1.57)
• Native Copilot integration

Best use cases:

• E2E testing with natural language
• Web scraping of JavaScript-heavy sites
• Form filling and data entry
• Price monitoring and comparison
• Interactive web research
• AI-driven autonomous testing

Next: Learn about Filesystem MCP Server → for local file access.

Questions about Playwright MCP? Check the official Playwright docs or the MCP server source.