How to Set Up Playwright MCP Server (2026)

The Playwright MCP server lets AI assistants control a real browser -- navigating pages, clicking elements, filling forms, taking screenshots, and running end-to-end tests. Instead of describing what you see on screen, your AI can interact with web pages directly through the Model Context Protocol.

This guide walks you through setting up the Playwright MCP server and connecting it to Claude Desktop, Cursor, VS Code, and Claude Code.

What Is the Playwright MCP Server?

The Playwright MCP server wraps Microsoft's Playwright browser automation library in an MCP-compatible interface. When connected to an AI assistant, it exposes tools that let the AI:

Navigate to URLs and interact with page elements
Click buttons, fill input fields, select options
Take screenshots of full pages or specific elements
Extract text content and page structure
Execute JavaScript in the browser context
Handle authentication flows and multi-page workflows

Why Use Playwright MCP Instead of Manual Testing?

Approach	Speed	Accuracy	AI Integration	Setup
Playwright MCP + AI	Fast	High	Native	Medium
Manual browser testing	Slow	High	None	None
Screenshot + AI	Fast	Low-Medium	Indirect	None
Selenium scripts	Medium	High	None	High
Cypress	Medium	High	None	Medium

Prerequisites

Requirement	Details
Node.js	v18 or higher
npm or yarn	For installing the MCP server
MCP-compatible client	Claude Desktop, Cursor, Cline, or Claude Code
Chromium	Playwright installs its own bundled browsers

Step 1: Install the Playwright MCP Server

The official Playwright MCP server is maintained by Microsoft. Install it globally or use npx to run it directly:

# Option 1: Run directly with npx (recommended)
npx @playwright/mcp@latest

# Option 2: Install globally
npm install -g @playwright/mcp

The first time you run it, Playwright will download browser binaries (Chromium, Firefox, WebKit). This may take a minute.

To install browsers manually:

npx playwright install

Step 2: Configure Claude Desktop

Add the Playwright MCP server to your Claude Desktop config file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop. You should see the hammer icon indicating MCP tools are available.

Running in Headed Mode (Visible Browser)

By default, Playwright runs headless (no visible browser window). To see the browser for debugging:

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

Specifying a Browser

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

Supported values: chromium (default), firefox, webkit.

Step 3: Configure Cursor

Add the Playwright MCP server in Cursor's settings or create a .cursor/mcp.json file in your project root:

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

Open Cursor Settings > MCP to verify the server is connected.

Step 4: Configure Cline (VS Code)

In the Cline extension settings, go to MCP Servers and add:

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

Cline will automatically detect the available tools when you start a new conversation.

Step 5: Configure Claude Code (CLI)

For Claude Code, add the Playwright MCP server to your global MCP config or pass it via the command line:

# Pass MCP config directly
claude --mcp-config playwright-mcp.json

Create a playwright-mcp.json file:

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

Or add it to ~/.claude/mcp_servers.json for persistent access:

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

Available MCP Tools

The Playwright MCP server exposes these tools to your AI assistant:

Tool	Description
`browser_navigate`	Navigate to a URL
`browser_click`	Click an element on the page
`browser_fill`	Type text into an input field
`browser_screenshot`	Take a screenshot of the page
`browser_select`	Select a dropdown option
`browser_hover`	Hover over an element
`browser_press_key`	Press a keyboard key
`browser_get_text`	Extract text content from an element
`browser_evaluate`	Execute JavaScript in the page
`browser_wait`	Wait for an element to appear
`browser_close`	Close the browser

Practical Use Cases

Testing a Web Application

Navigate to http://localhost:3000/login and test the login flow:
1. Fill in the email field with "test@example.com"
2. Fill in the password field with "password123"
3. Click the "Sign In" button
4. Take a screenshot to verify the dashboard loaded
5. Check if the welcome message says "Welcome, Test User"

The AI will execute each step using the Playwright MCP tools and report the results.

Scraping Documentation

Go to https://platform.openai.com/docs/api-reference/chat/create
and extract all the request parameters, their types, and descriptions.
Format them as a TypeScript interface.

Visual Regression Testing

Navigate to http://localhost:3000 and take screenshots of:
1. The homepage hero section
2. The pricing page
3. The login page
4. The dashboard (after logging in with test credentials)

Compare each screenshot with the design specs and report any visual differences.

Automated Form Testing

Go to http://localhost:3000/signup and test form validation:
1. Submit the form empty and screenshot the error messages
2. Enter an invalid email and check the validation
3. Enter a password shorter than 8 characters and check
4. Fill everything correctly and verify successful submission

Advanced Configuration

Using a Custom User Data Directory

Persist cookies and sessions between runs:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-data-dir", "/tmp/playwright-mcp-data"
      ]
    }
  }
}

Setting a Custom Viewport

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

Generating Playwright Test Code

One powerful workflow is asking the AI to interact with your app and then generate reusable Playwright test scripts:

Navigate through the checkout flow on http://localhost:3000/shop:
1. Add a product to cart
2. Go to checkout
3. Fill in shipping details
4. Complete the purchase

Then generate a Playwright test file (checkout.spec.ts) that
automates this entire flow for CI/CD.

The AI uses the MCP tools to interact with the app, then writes a proper Playwright test based on what it learned.

Troubleshooting

"Browser failed to launch": Run npx playwright install to ensure browser binaries are downloaded. On Linux, you may also need system dependencies: npx playwright install-deps.

"Element not found" errors: Web pages may take time to load. Ask the AI to use browser_wait before interacting with elements. Dynamic SPAs often need explicit waits.

Screenshots are blank or black: This can happen in headless mode on some systems. Try running with --headed to debug, or ensure your GPU drivers are up to date.

High memory usage: The Playwright browser instance consumes memory. Close the browser between sessions using browser_close. Avoid opening many tabs simultaneously.

MCP server disconnects after timeout: Some MCP clients have idle timeouts. If the browser has been idle for too long, the server may disconnect. Restart the conversation to reconnect.

Wrapping Up

The Playwright MCP server bridges the gap between AI assistants and real browser interactions. Instead of describing screenshots or manually running tests, your AI can directly navigate, interact with, and validate your web application. Combined with AI-generated test scripts, this becomes a powerful workflow for both development and QA.

If your project involves AI-generated media such as images, video, or talking avatars, check out Hypereal AI for a unified API that handles all media generation with pay-as-you-go pricing.

Try Hypereal AI free -- 35 credits, no credit card required.