How to Set Up Playwright MCP Server (2026)
Connect browser automation to AI assistants with MCP
Start Building with Hypereal
Access Kling, Flux, Sora, Veo & more through a single API. Free credits to start, scale to millions.
No credit card required • 100k+ developers • Enterprise ready
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.
Related Articles
Start Building Today
Get 35 free credits on signup. No credit card required. Generate your first image in under 5 minutes.
