Playwright MCP: Setup for Cursor, Claude Code and VS Code, and When to Use It for Scraping

Playwright MCP is Microsoft's Model Context Protocol server that lets an AI agent drive a real browser through Playwright: it opens pages, reads them as accessibility snapshots, and clicks, types and fills forms by element reference. You add it to Cursor, Claude Code or VS Code with one command, npx @playwright/mcp@latest, and your agent can browse within a minute.

This guide covers the setup for each client from the official README, the options and tools you'll actually use, what a snapshot looks like in a real session, and an honest look at using it for web scraping: where it shines, and where to hand the job to the Scrape.ly MCP server. Everything was checked on 22 October 2026 against version 0.0.83.

The server at a glance

How it works

The server keeps a browser open and gives the agent tools such as browser_navigate, browser_click and browser_type. After each step the agent reads the page as an accessibility tree: roles, names and text, each element tagged with a ref the next tool call can target. No vision model is needed.

On 22 October 2026 we started version 0.0.83 on a Mac with --headless --isolated, called it from a short Python script over stdio, and asked for a snapshot of quotes.toscrape.com/js, a test page whose content is rendered by JavaScript. The start of the real response:

- generic [active] [ref=e1]:
  - generic [ref=e2]:
    - generic [ref=e3]:
      - heading [level=1] [ref=e5]:
        - link "Quotes to Scrape" [ref=e6] [cursor=pointer]:
          - /url: /
      - paragraph [ref=e8]:
        - link "Login" [ref=e9] [cursor=pointer]:
          - /url: /login
    - generic [ref=e10]:
      - generic [ref=e11]: “The world as we have created it is a process of our thinking. It cannot be changed without changing our thinking.”
      - generic [ref=e12]: by Albert Einstein
      - generic [ref=e13]: "Tags: change deep-thoughts thinking world"

To click "Login", the agent calls browser_click with target e9. That's the whole model: read the tree, act on a ref, read again.

How to install the Playwright MCP server

Playwright MCP in Cursor

Add it to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). This is the README's standard config:

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

Or open Cursor Settings → MCP → Add new MCP Server, choose the command type and enter npx @playwright/mcp@latest.

Playwright MCP in Claude Code

claude mcp add playwright npx @playwright/mcp@latest

To pass options, put the command after -- so Claude Code doesn't read the server's flags as its own:

claude mcp add playwright -- npx @playwright/mcp@latest --headless --isolated

In VS Code

From a terminal:

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

Or run MCP: Add Server from the Command Palette, choose Command (stdio) and enter npx -y @playwright/mcp@latest. Note that VS Code's own .vscode/mcp.json format uses a top-level servers key, while Cursor, Claude Desktop and most other clients use mcpServers.

The same standard config works in Claude Desktop, Windsurf, Cline, Goose and other MCP clients. Once connected, try: "Navigate to https://demo.playwright.dev/todomvc and add a few todo items."

Options worth knowing

Add options to the args list after the package name.

Two practical notes from the README. A persistent profile can be used by only one browser at a time, so start a second client with --isolated or its own --user-data-dir. And headless browsers close after an hour without tool calls; --idle-timeout changes that.

The tools your agent gets

The always-on core set covers what browsing needs: browser_navigate, browser_navigate_back, browser_snapshot, browser_find, browser_click, browser_hover, browser_type, browser_fill_form, browser_select_option, browser_press_key, browser_take_screenshot, browser_tabs, browser_wait_for, browser_evaluate, browser_network_requests and a few more. In our session, tools/list returned 25 tools. Opt-in groups add network mocking, cookie and storage management, test assertions, tracing and video, PDF export and coordinate-based mouse control; the tool reference lists them all.

One tool deserves a warning: browser_run_code_unsafe runs arbitrary Playwright code in the server process, which the docs call "RCE-equivalent". Only allow it for clients you trust.

MCP server or Playwright CLI?

Microsoft now also ships the Playwright CLI for coding agents, and its own docs explain the split. The CLI is more token-efficient because the agent runs short shell commands instead of loading tool schemas and full snapshots into context. MCP suits agent loops that need persistent browser state and rich page introspection, such as exploratory automation or long-running workflows.

Puppeteer MCP: archived

If you searched for "Puppeteer MCP", the reference server @modelcontextprotocol/server-puppeteer is deprecated on npm and lives in the archived servers repository, which provides "NO SECURITY GUARANTEES". The Puppeteer project itself now points to chrome-devtools-mcp, a Puppeteer-based server aimed at browser automation and debugging. For an agent that browses, Playwright's server is the maintained choice.

Playwright MCP for web scraping: where it shines, and where to hand off

The server is excellent at the exploratory half of scraping:

• Figuring out a page. "Open this listing, find where the price and stock status are, and tell me the selectors." The agent sees the real rendered page, including JavaScript content.
• One-off reads. Pulling a table from one page, checking a value behind a few clicks, or reading a site where you're logged in through the persistent profile.
• Writing the scraper. The agent can explore the site in the browser, then write a Playwright script for you. See our Playwright vs Selenium guide for what that script looks like.

It is the wrong tool for volume, and the reasons are structural:

• Every page goes through the model. In our test, the snapshot of one simple page holding 10 short quotes was 3,456 characters. Pages with more elements produce longer snapshots, and the model reads each one in full, at token prices, for every page it visits.
• One local browser. The server drives a browser on your machine, from your IP. Sites that block automation will block it too; the README is explicit that it is "not a security boundary", and it has no anti-bot layer.
• No scheduling, storage or retries. When the chat ends, the job ends.

That is where the Scrape.ly MCP server takes over. Instead of driving a browser, the agent calls search-actors to find a ready-made scraper in the Scrape.ly Store, fetch-actor-details to read its input schema, call-actor to run it in the cloud, and get-actor-output to read structured results page by page. The work happens in the cloud with proxies included; only the rows the agent asks for come back, with long text values cut to keep replies small. A run of the Website Content Crawler that saved 5 pages as clean text and Markdown cost $0.0031 in our crawling guide, and the Google Maps Scraper returns places at $3.60 per 1,000.

Both servers in one mcp.json

You don't have to choose. This Cursor config gives the agent a local browser for exploring and Scrape.ly for collecting:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--isolated"]
    },
    "scrapely": {
      "url": "https://api.scrape.ly/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Drop the headers block and Cursor offers to sign in to Scrape.ly with OAuth instead. In Claude Code, add the second server with claude mcp add --transport http scrapely https://api.scrape.ly/mcp and sign in with /mcp.

Then split the work in the prompt: "Use playwright to open the Google Maps results for coffee shops in Seattle and tell me which fields each place card shows. Then use scrapely to run cornerledger/google-maps-scraper for 'coffee shop' in 'Seattle, WA', 50 places, with a maximum charge of $0.50, and give me a CSV of name, rating and phone."

For an agent you don't watch, give it a scoped Scrape.ly API key: the Read only preset, or actors:run plus runs:read with a daily charge limit. The MCP docs list the scopes and every tool.

For a wider comparison of scraping servers for agents, see our roundup of the best MCP servers for web scraping.

What to watch out for

• Logged-in profiles. The default persistent profile keeps your logins. Anything the agent can reach, it can click. Use --isolated when you don't need a session.
• Unsafe code tool. Keep browser_run_code_unsafe for trusted clients only.
• Context size. Large pages produce large snapshots. Ask for one section, use browser_find, or let the agent save snapshots to a file.
• Parallel clients. Two clients sharing one persistent profile conflict; give each its own profile.
• Site rules. An agent browsing for you is still collecting data, so the same terms, privacy and copyright rules apply as to any scraper.

FAQ

What is Playwright MCP?

It's an open-source Model Context Protocol server from Microsoft that exposes Playwright browser automation as tools an AI agent can call. The agent reads pages as accessibility snapshots and acts on element references, so no screenshots or vision model are needed.

Is it free?

Yes, the server is open source and runs on your machine. You pay only for the model tokens your agent uses, which grow with the size of the pages it reads.

How do I add it to Claude Code with options?

Run claude mcp add playwright npx @playwright/mcp@latest. To pass options such as --headless, use claude mcp add playwright -- npx @playwright/mcp@latest --headless, with the -- before the command.

Can it run headless?

Yes. It runs headed by default so you can watch; add --headless to the args list. Headless browsers close after an hour without tool calls unless you change --idle-timeout.

What's the difference between Puppeteer MCP and Playwright's server?

The Puppeteer reference server is deprecated and archived, with no security updates. Playwright's server is maintained by Microsoft, drives Chrome, Firefox, WebKit or Edge, and works through accessibility snapshots.

Can Playwright MCP scrape websites?

It can read and extract data from pages your agent visits, which is ideal for exploring a site or a one-off pull. For hundreds of pages, scheduled jobs or sites that block bots, have the agent run a ready-made scraper through the Scrape.ly MCP server instead.