Playwright MCP Server: Setup with Claude Desktop, Cursor & VS Code (2026)

Quick answer: Playwright MCP Server is an open-source bridge built by Microsoft that lets AI assistants like Claude, ChatGPT, and Cursor control real web browsers through structured commands. Installation takes about 5 minutes with npx @playwright/mcp@latest and a JSON config entry in your AI client. Microsoft released it on March 22, 2025 under Apache 2.0 license. It has 33,000+ GitHub stars and ranks as the #1 most-used MCP server on the global leaderboard.

What Is Playwright MCP Server?

Playwright MCP Server is a bridge between AI assistants and real web browsers. Built by Microsoft on top of their Playwright testing framework, it exposes browser automation capabilities through the Model Context Protocol (MCP) — the open standard that lets AI tools interact with external services.

In plain terms: instead of taking screenshots and guessing what's on screen, your AI assistant sends structured commands to the Playwright MCP Server, which executes them in a real browser and returns structured results. It's faster, more reliable, and works without vision models.

The server enables actions like navigating to pages, clicking elements, filling forms, extracting text, running JavaScript, and taking screenshots — all orchestrated by an AI through natural language prompts.

The Numbers Behind Playwright MCP

Playwright itself launched on January 31, 2020) as Microsoft's answer to Puppeteer. By 2025 the underlying framework had accumulated 75,000+ GitHub stars, 20+ million all-time NPM downloads, and 11,000+ Stack Overflow questions) — making it the fastest-growing modern web testing framework.

The MCP server wrapper came later, on March 22, 2025. Adoption was unusually fast: within twelve months the official microsoft/playwright-mcp repository crossed 33,000 GitHub stars and ranked #1 on PulseMCP's MCP server leaderboard — ahead of every other MCP server in the public registry.

Microsoft's own framing of why this design wins, from the official README:

> "This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models. Fast and lightweight. Uses Playwright's accessibility tree, not pixel-based input. LLM-friendly. No vision models needed, operates purely on structured data. Deterministic tool application."

In other words: the AI doesn't squint at pixels. It reads the same accessibility tree screen readers use — the page's actual structure. That's why it's faster, cheaper in tokens, and less prone to hallucinated clicks than vision-based browser agents.

Why Playwright MCP Matters

Traditional browser automation requires writing detailed scripts with selectors, waits, and error handling. With Playwright MCP, you describe what you want in plain language, and the AI translates that into precise Playwright commands.

This changes the game for:

• QA and testing teams who can describe test scenarios instead of coding them
• Business automation where AI agents need to interact with web applications that lack APIs
• Development workflows where AI assistants verify their code changes in a real browser
• Data extraction from websites that require authentication or interaction

Prerequisites

Before setting up Playwright MCP Server, make sure you have:

• Node.js 18 or newer — Check with node --version
• A compatible MCP client — Claude Desktop, VS Code with GitHub Copilot, Cursor, or Windsurf
• A terminal — For running installation commands

Installation Methods

Method 1: Quick Install with npx (Recommended)

The fastest way to get started — no global installation needed:

npx @playwright/mcp@latest

This downloads and runs the latest Playwright MCP Server. It works with any MCP-compatible client.

Method 2: Global Installation via npm

If you want the server permanently available:

npm install -g @playwright/mcp

Method 3: Via Smithery (for Claude Desktop)

Smithery provides one-click installation for Claude Desktop:

npx @smithery/cli install @playwright/mcp --client claude

Connecting to Your AI Client

Claude Desktop

Edit your Claude Desktop configuration file (claude_desktop_config.json):

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

On macOS, this file is at: ~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop, and you can now say: "Use Playwright to open example.com and tell me what's on the page."

VS Code with GitHub Copilot

Run this command in your terminal:

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

Or go to VS Code Settings → Extensions → MCP Servers and add it through the UI.

Cursor

Go to Cursor Settings → MCP → Add new MCP Server. Set the type to "command" and enter:

npx @playwright/mcp@latest

Claude Code (CLI)

For Claude Code users working in the terminal:

claude mcp add playwright npx @playwright/mcp@latest

This persists per-directory in your .claude.json configuration.

Configuration Options

Playwright MCP Server supports extensive configuration through command-line arguments and environment variables:

Browser Selection

By default, Playwright MCP launches Chromium. You can switch browsers:

{

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

Options: chrome, firefox, webkit, msedge

Headless vs. Headed Mode

By default, the browser runs headed (visible). For CI/CD or server environments, use headless:

{

  "args": ["-y", "@playwright/mcp@latest", "--headless"]
}

Vision Mode

Enable screenshot capabilities alongside accessibility tree data:

{

  "args": ["-y", "@playwright/mcp@latest", "--caps", "vision"]
}

Custom Port and Host

For remote or multi-client setups:

{

  "args": ["-y", "@playwright/mcp@latest", "--port", "3100", "--host", "0.0.0.0"]
}

How Playwright MCP Works Under the Hood

Unlike screenshot-based AI automation, Playwright MCP uses the browser's accessibility tree — a structured representation of all interactive elements on the page. This is the same technology screen readers use.

When you ask the AI to "click the login button," here's what happens:

1. The AI sends a tool call to the Playwright MCP Server

2. The server queries the page's accessibility tree for a button labeled "login"

3. It executes a precise Playwright click action on that element

4. The server returns the updated page state to the AI

This approach is deterministic and fast — no image processing, no guessing, no pixel coordinates.

Available Tools

Playwright MCP exposes these core tools to AI clients:

• browser_navigate — Go to a URL
• browser_click — Click an element by its accessibility reference
• browser_type — Type text into an input field
• browser_snapshot — Get the current page's accessibility tree
• browser_screenshot — Capture a screenshot (when vision capability is enabled)
• browser_evaluate — Execute JavaScript in the page context
• browser_wait — Wait for a specific condition
• browser_select_option — Select from dropdown menus
• browser_drag — Drag and drop elements
• browser_tab_list — List open tabs
• browser_tab_new — Open a new tab
• browser_tab_close — Close a tab

Practical Use Cases

1. Automated Testing

Describe test scenarios in natural language:

"Navigate to our login page, enter the test credentials, click submit, and verify the dashboard loads with the user's name displayed."

The AI translates this into a series of Playwright MCP tool calls and reports whether the test passed.

2. Web Scraping with Authentication

For sites that require login or interaction:

"Log into our supplier portal, navigate to the orders section, and extract all pending orders from the last 7 days."

3. Form Filling and Data Entry

"Open our CRM, create a new contact with these details: [name, email, company], then assign them to the sales pipeline."

4. Visual Regression Testing

With vision mode enabled, the AI can compare screenshots before and after code changes to identify unexpected visual differences.

Troubleshooting Common Issues

Server Won't Start

Check that Node.js 18+ is installed. If you see port conflicts, specify a different port with --port 3100.

Browser Doesn't Launch

Playwright needs browser binaries. Install them with:

npx playwright install chromium

Elements Not Found

The accessibility tree might not include all elements. Try enabling vision mode for a fallback, or check if the page uses iframes or shadow DOM that need special handling.

Slow Performance

Large pages generate large accessibility trees. Use --caps vision for complex pages where the tree is too dense, or navigate to specific sections before querying.

Playwright MCP vs. Playwright CLI

Microsoft now offers two approaches:

Playwright MCP is protocol-based — the AI sends structured commands and gets structured responses. Best for integration with AI assistants in IDE and chat contexts.

Playwright CLI + SKILLS is command-line based — the AI runs shell commands directly. More token-efficient for coding agents that work with large codebases.

For most users, Playwright MCP is the easier starting point. Switch to CLI + SKILLS if you're building high-throughput coding agents that need to minimize context window usage.

What Digidog Builds with MCP

At Digidog, we use MCP extensively — not just Playwright MCP, but custom MCP servers connecting AI to CRM systems, project management tools, databases, email, and more.

Playwright MCP is one piece of the puzzle. The real power comes from combining multiple MCP servers so your AI assistant can browse the web, update your CRM, send emails, and manage tasks — all from a single conversation.

If you're exploring MCP for your business, we build custom integrations from strategy to production — see our AI Integration service for the broader picture, or book a free consultation to discuss your specific use case.

Frequently Asked Questions

Is Playwright MCP free?

Yes. Playwright MCP is released by Microsoft under the Apache 2.0 license and is free to use. You'll need access to an AI model (Claude, ChatGPT, etc.) to drive it, which may have its own subscription costs.

Does Playwright MCP work with Claude Desktop?

Yes. Playwright MCP works with any MCP-compatible client, including Claude Desktop, Claude Code, Cursor, VS Code (via GitHub Copilot), Windsurf, and Kiro. Configuration is identical across clients — only the config file location differs.

How is Playwright MCP different from regular Playwright?

Regular Playwright requires you to write code (TypeScript or Python) with explicit selectors and waits. Playwright MCP exposes the same browser automation capabilities to an AI assistant through the Model Context Protocol, so you describe what you want in natural language and the AI translates that into Playwright commands.

Can Playwright MCP run headless on a server?

Yes. Pass --headless in the config to run without a UI. For containerized environments or remote servers, you can also start it with HTTP transport using --port 8931 and connect from anywhere.

Why doesn't Playwright MCP need a vision model?

Playwright MCP uses the browser's accessibility tree — the same structured representation screen readers use — instead of pixels. This is faster, more deterministic, and avoids the cost of vision model calls.