--- title: "Playwright MCP: Setup Guide and Scraping Tips | Scrape.ly" description: "Set up Playwright MCP in Cursor, Claude Code and VS Code: install command, config, key options and tools, and when to hand scraping off to Scrape.ly." url: https://scrape.ly/blog/playwright-mcp markdown: https://scrape.ly/blog/playwright-mcp.md --- [AI agents](https://scrape.ly/blog/category/ai-agents.md) # Playwright MCP: Setup for Cursor, Claude Code and VS Code, and When to Use It for Scraping Playwright MCP lets an AI agent drive a real browser through accessibility snapshots. Set it up in Cursor, Claude Code or VS Code in a minute, learn the options and tools that matter, and see where it shines for scraping and where to hand off. [Scrape.ly Team The team behind Scrape.ly](https://scrape.ly/blog/author/scrapely-team.md) - Published Oct 23, 2026 - Reading time 8 min read ![Pixel-art robot with an orange >\_ on its terminal head carries a cable from a browser window showing the Playwright logo into a server rack labelled MCP](https://scrape.ly/media/playwright-mcp.png?w=1080) 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 | | | | ------------------------ | -------------------------------------------------------------------------------------------------- | | Package | `@playwright/mcp` (0.0.83 on 22 October 2026) | | Runs | Locally, started by your MCP client with `npx` | | Needs | Node.js 20 or newer, per the [Playwright docs](https://playwright.dev/docs/getting-started-mcp) | | How the agent sees pages | Accessibility snapshots with element refs such as `[ref=e5]`, not screenshots | | Browser | Chrome, Firefox, WebKit or Edge; headed by default | | Default tools | Navigation, clicks, typing, forms, tabs, screenshots, JavaScript evaluation, network request lists | | Extra tools | `--caps` for vision (coordinates), PDF, DevTools and more | | Profile | Persistent by default, so logins survive between sessions; `--isolated` for a clean one | ## 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](https://quotes.toscrape.com/js/), a test page whose content is rendered by JavaScript. The start of the real response: ```plaintext 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: ```json { "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 ```shell 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: ```shell claude mcp add playwright -- npx @playwright/mcp@latest --headless --isolated ``` ### In VS Code From a terminal: ```shell 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. | Option | What it does | | ------------------------ | ------------------------------------------------------------------------------ | | `--headless` | Run without a visible window (headed is the default) | | `--browser ` | `chrome`, `firefox`, `webkit` or `msedge` | | `--isolated` | Keep the profile in memory; every session starts clean | | `--user-data-dir ` | Use a specific persistent profile | | `--storage-state ` | Load cookies and local storage into an isolated session | | `--caps ` | Extra tools: `vision`, `pdf`, `devtools` | | `--proxy-server ` | Send browser traffic through a proxy | | `--device "iPhone 15"` | Emulate a device | | `--port ` | Run as a standalone HTTP server, then connect to `http://localhost:/mcp` | 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](https://playwright.dev/mcp/introduction) 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](https://github.com/modelcontextprotocol/servers-archived), 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](https://scrape.ly/blog/playwright-vs-selenium.md) 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](https://scrape.ly/mcp.md) takes over. Instead of driving a browser, the agent calls `search-actors` to find a ready-made scraper in the [Scrape.ly Store](https://scrape.ly/store.md), `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](https://scrape.ly/store/querystone/website-content-crawler.md) that saved 5 pages as clean text and Markdown cost $0.0031 in our [crawling guide](https://scrape.ly/blog/web-crawling-vs-web-scraping.md), and the [Google Maps Scraper](https://scrape.ly/store/cornerledger/google-maps-scraper.md) returns places at $3.60 per 1,000. | Job | Playwright MCP | Scrape.ly MCP | | ------------------------------------- | ---------------------------------- | ----------------------------------------------------------------- | | Explore a page, find selectors | Best fit | Not needed | | Act inside your own logged-in session | Best fit | Not its job | | Hundreds or thousands of records | Each page passes through the model | One `call-actor`, results paged | | Sites that block bots | Your machine, your IP | Proxies included, maintained Actors | | Structured fields | The agent parses snapshots | Actor output schema, JSON/CSV/Excel | | Spending control | Token budget only | `maxTotalChargeUsd` per run, scoped keys with daily charge limits | ## 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: ```json { "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](https://scrape.ly/docs/mcp.md) 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](https://scrape.ly/blog/best-mcp-servers-for-web-scraping.md). ## 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. About the author [Scrape.ly Team](https://scrape.ly/blog/author/scrapely-team.md) The team behind Scrape.ly Scrape.ly is the web data platform from TeraShift GmbH in Switzerland, powered by Evomi: ready-made scrapers in the Scrape.ly Store, a cloud runtime, an API with JavaScript and Python SDKs, proxies, a hosted anti-bot browser and an MCP server for AI agents. - [Website](https://scrape.ly/index.md) Keep reading ## More in AI agents - [![Pixel-art robot with an orange >\_ on its terminal head, an AI sparkle in a speech bubble above it, reaches out to a standing text file with a folded corner whose dark plate reads LLMS, next to a web page](https://scrape.ly/media/what-is-llms-txt.png?w=750)](https://scrape.ly/blog/what-is-llms-txt.md) ### [What Is llms.txt? Format, Real Examples and How to Create One](https://scrape.ly/blog/what-is-llms-txt.md) [llms.txt is a Markdown file at the root of a website that gives AI agents a short, curated map of its content. The format rules from the v2 proposal, real files from Anthropic, OpenAI, Stripe and Cloudflare, llms-full.txt, Markdown twins, and how to create one in 11 seconds.](https://scrape.ly/blog/what-is-llms-txt.md) - [![Pixel-art robot with an orange >\_ on its terminal head pulls a page of text out of a monitor showing the cyan Crawl4AI logo above lines of code, and drops it into a crate](https://scrape.ly/media/crawl4ai-guide.png?w=750)](https://scrape.ly/blog/crawl4ai-guide.md) ### [Crawl4AI Tutorial: Setup, Examples and a Hosted Alternative](https://scrape.ly/blog/crawl4ai-guide.md) [A tested Crawl4AI tutorial for v0.9.5: install it, crawl a page to Markdown, extract JSON with CSS selectors or an LLM, deep crawl a site, run it in Docker or over MCP, and see when a hosted crawler saves you the infrastructure.](https://scrape.ly/blog/crawl4ai-guide.md) - [![Pixel-art robot with an orange >\_ on its terminal head carries a cable from an office tower with the blue LinkedIn logo on its sign into a server rack labelled MCP](https://scrape.ly/media/linkedin-mcp.png?w=750)](https://scrape.ly/blog/linkedin-mcp.md) ### [LinkedIn MCP: Give Claude, Cursor and ChatGPT LinkedIn Data Without Your Login](https://scrape.ly/blog/linkedin-mcp.md) [A LinkedIn MCP server lets your AI agent pull company pages, job listings, posts and ads into the chat. Set one up in Claude, Cursor or ChatGPT in a minute, without handing over your LinkedIn session, and see the exact tool calls and what came back.](https://scrape.ly/blog/linkedin-mcp.md) ## The internet is full of data. Start owning yours. Scrape.ly gives you the infrastructure, the tooling, and the team to extract, process, and operationalize web data at any scale. Setup takes minutes. The advantage lasts forever. [Get Started Free](https://my.scrape.ly/register) [Chat with Support](mailto:support@scrape.ly?subject=Question%20about%20Scrape.ly\&body=Hi%2C%20I%20have%20a%20question%20about%20Scrape.ly.) No credit card. No setup calls.