Automate Browser Tasks with Claude Code and the Playwright MCP Server

What Claude Code and Playwright CLI Actually Do Together

If you’ve been looking for a way to give Claude Code real browser control — not just code generation, but actual interaction with live websites — the Playwright CLI integration is the most reliable approach available right now.

Claude Code automation with Playwright CLI lets Claude navigate pages, click elements, fill forms, take screenshots, extract data, and handle authenticated sessions. It does this by connecting Claude to a running browser instance through a Model Context Protocol (MCP) server. Claude issues commands; the browser executes them.

This is meaningfully different from screenshot-based computer use. Playwright gives Claude structured access to the DOM, network requests, and page state — not just pixels on a screen. That makes it faster, more reliable, and far less prone to visual misidentification.

This guide covers setup from scratch, the three main use cases where this combo shines, and what to watch out for before you build anything production-facing.

Prerequisites

Before starting, make sure you have the following in place:

Claude Code installed and working (requires an Anthropic API key or Claude Max subscription)
Node.js 18+ installed on your machine
npm or npx available in your terminal
A basic understanding of what MCP servers do — if you’re new to this, the overview of MCP servers and how they work is a good starting point

You don’t need to write Playwright code yourself. Once the integration is configured, Claude handles the scripting. Your job is to describe what you want automated in plain language.

How the Playwright MCP Server Works

Playwright’s MCP server is the bridge between Claude Code and the browser. It exposes browser control as a set of tools Claude can call — things like navigate, click, type, screenshot, evaluate, and wait_for_selector.

When you ask Claude to “log into this site and extract the table of results,” it’s not writing a script and running it separately. It’s issuing tool calls in real time, reading the results of each action, and deciding what to do next. This is the core of agentic browser automation: the model sees the page state and responds to it.

There are two packages worth knowing:

@playwright/mcp — the official Playwright MCP server maintained by Microsoft. This is the standard choice.
playwright-mcp — an earlier community implementation. Functional, but the official package has caught up.

For new setups, use @playwright/mcp.

Step-by-Step Setup

Step 1: Install the Playwright MCP Server

Run this in your terminal:

npx @playwright/mcp@latest

This installs and starts the MCP server. On first run, Playwright will also install the browser binaries it needs (Chromium by default).

If you want to install it globally:

npm install -g @playwright/mcp

Step 2: Register the Server with Claude Code

Claude Code reads its MCP configuration from a JSON file. You need to add the Playwright server to that file.

The configuration file lives at:

macOS/Linux: ~/.claude/mcp_servers.json
Windows: %APPDATA%\Claude\mcp_servers.json

If the file doesn’t exist yet, create it. Add the following:

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

If you want to use a specific browser or run in headless mode, you can pass additional arguments:

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

Supported browsers: chromium, firefox, webkit. Headless mode runs the browser without a visible window — useful for server environments.

Step 3: Verify the Connection

Start Claude Code in your project directory:

claude

Then ask Claude something simple to confirm the browser tools are available:

What browser tools do you have access to?

Claude should list the available Playwright tools. If it doesn’t, check that the MCP config file is saved correctly and that npx @playwright/mcp@latest runs without errors on your machine.

Step 4: Run Your First Automation

Once connected, you can start issuing browser tasks directly in Claude Code:

Open https://example.com, take a screenshot, and tell me what's on the page.

Claude will navigate to the URL, capture a screenshot, and describe the content. From here, you can build toward more complex workflows.

Use Case 1: QA Testing and Regression Checks

QA testing is where the Claude Code + Playwright combination is most immediately useful for engineering teams. You describe what you want to test; Claude writes and executes the test in one pass.

Writing Tests Without Writing Tests

Instead of authoring Playwright test scripts manually, you can tell Claude:

Go to our staging environment at https://staging.myapp.com. 
Log in with test@example.com / testpassword123.
Navigate to the checkout flow and verify that:
1. The cart total updates when you change quantity
2. The promo code field accepts "SAVE10" and reduces the total by 10%
3. The place order button is disabled if the shipping address is empty

Claude will walk through each step, observe the actual page behavior, and report pass/fail on each condition. It can also take screenshots at each stage if you want a visual record.

Catching Regressions on Deploy

Pair this with a scheduled trigger and you have a basic regression testing pipeline. You can build a scheduled browser automation agent that runs your QA checklist after every deployment and logs the results somewhere accessible.

When to Use This vs. Traditional Playwright Tests

Claude-driven QA is exploratory and fast to set up. Traditional Playwright test suites are better for CI/CD pipelines that need to run deterministically at scale. The two approaches complement each other — use Claude to draft and prototype test flows, then codify the critical ones into proper test scripts.

Use Case 2: Web Scraping and Data Extraction

Web scraping is the other high-value use case for this setup. Playwright handles dynamic, JavaScript-heavy pages that basic HTTP scrapers can’t touch. Claude handles the reasoning: figuring out what’s actually meaningful on the page, how to navigate pagination, and how to clean up the output.

Basic Scraping Example

Go to https://news.ycombinator.com. 
Scrape the top 20 stories: title, URL, and points. 
Format the results as a JSON array and save it to results.json.

Claude navigates the page, identifies the relevant elements, extracts the data, and writes the file. No selector hunting required on your part.

Handling Pagination

Go to https://site.com/products?category=electronics.
Scrape all product names and prices from every page.
Stop when you reach the last page or after 10 pages, whichever comes first.

Claude tracks page state, follows “next” links, and applies your stop condition. For more complex scraping logic — incremental runs, deduplication, token management — see the guide on building scraping skills with incremental runs and stop conditions.

Avoiding Token Bloat

Scraping can burn through tokens fast if Claude is parsing entire page HTML repeatedly. Keep prompts specific about what data you need, and consider asking Claude to extract only the relevant section of the DOM rather than processing the full page. There’s a solid breakdown of token-saving techniques for web scraping agents worth reading before you build anything at scale.

Use Case 3: Authenticated Browser Sessions

This is the use case most people underestimate. Playwright maintains persistent browser state, including cookies and local storage. That means Claude can log into a site once and maintain that session across multiple tasks in the same session.

Logging In and Staying Logged In

Log into https://app.mycrm.com with username: admin@company.com, password: [stored in env var ADMIN_PASS].
Once logged in, go to the Contacts section and export all contacts added in the last 30 days as a CSV.

Claude handles the login flow, navigates to the right section, and triggers the export. If there’s a multi-step login (like a verification code), Claude will wait and ask you to provide it.

Handling Multi-Factor Authentication

MFA is a real complication. Playwright can handle SMS-based MFA if you can pipe the code in, but TOTP (authenticator app) flows require you to provide the code manually. The recommended approach:

Run the login automation
Claude pauses when it hits the MFA prompt
You provide the code
Claude continues

For sites with aggressive bot detection, authenticated sessions through Playwright are more reliable than cookie injection approaches. If you’re running into blocks on sites like LinkedIn, the guide on bypassing browser automation blocks covers specific mitigation strategies.

Reusing Session State

Playwright supports saving browser context (cookies, storage) to a file and reloading it later. This means you can log in once, save the session, and reuse it across multiple automation runs without re-authenticating each time.

To save state:

After logging in, save the browser session state to ./auth-state.json

To restore:

Load the saved session from ./auth-state.json and then navigate to the dashboard.

This is particularly useful for multi-agent Chrome automation setups where multiple Claude instances need to operate on the same authenticated account without each logging in separately.

Running Multiple Browser Tasks in Parallel

Once you have the basic setup working, the natural next question is: can Claude run several browser tasks at the same time?

Yes, with some configuration. Each parallel agent needs its own browser context to avoid session conflicts. You can spin up multiple Claude Code instances, each with their own Playwright connection, and coordinate them through shared output files or a task queue.

The parallel browser agents guide covers the architecture for this in detail. The short version: don’t share browser contexts between agents, do share output state through the filesystem or a database, and set clear stop conditions so agents don’t duplicate work.

Headless vs. Headed Mode: When to Use Each

Headed mode (with a visible browser window) is better for:

Development and debugging — you can see exactly what Claude is doing
Sites that detect headless browsers and serve different content
MFA flows where you need to intervene manually

Headless mode is better for:

Production automation running on servers
Scheduled tasks where no one is watching
Faster execution when visual feedback isn’t needed

Switch between them by passing or omitting the --headless flag in your MCP config. You can also override this per-session by updating the config and restarting the MCP server.

For fully unattended automation, Claude Code headless mode is worth understanding as a complement — it lets Claude Code itself run without an interactive terminal, which pairs well with headless Playwright for end-to-end autonomous pipelines.

Token and Cost Considerations

Every browser action generates tool call results that count toward your token usage. Screenshots, in particular, are expensive — image data adds significant token overhead.

Practical tips to keep costs reasonable:

Request screenshots only when necessary. Don’t ask Claude to screenshot every step unless you need the visual record.
Be specific in your prompts. “Extract the price from the product page” is cheaper than “Tell me everything on this page.”
Set explicit stop conditions. Without them, Claude may keep browsing when it’s already done. Clear termination criteria prevent unnecessary tool calls.
Avoid re-processing the same data. If Claude already extracted a table, don’t send it back to the model to reformat — do that transformation in code.

For a deeper look at managing costs in agentic workflows, Claude Code’s approach to token budget management and MCP server token overhead are both worth reading before you scale.

Common Problems and How to Fix Them

MCP Server Not Connecting

Symptom: Claude says it doesn’t have browser tools, or the Playwright server doesn’t start.

Fix: Run npx @playwright/mcp@latest directly in your terminal first. If it errors, you’ll see the actual problem — usually a missing Node version or network issue during browser binary download. Fix that before worrying about the Claude Code config.

Browser Closes Immediately

Symptom: Claude opens a browser but it closes before any action completes.

Fix: This usually means the MCP server process is exiting. Check that the server is running in the background. If you’re using npx, make sure it’s not timing out. Try installing the package globally to avoid npx latency.

Site Blocks Playwright

Symptom: The site serves a CAPTCHA, bot detection page, or returns empty content.

Fix: Switch from headless to headed mode first — many detection systems treat headless browsers differently. Slow down action sequences. Use realistic user agent strings. For persistent blocking, see the approach to bypassing automation blocks on difficult sites.

Claude Gets Stuck in Loops

Symptom: Claude keeps clicking or navigating without making progress.

Fix: Add explicit stop conditions to your prompt: “If you’ve been on the same page for more than 3 attempts without progress, stop and report what you see.” Clear exit criteria are the single most effective tool for preventing runaway agent behavior. The broader principle is covered in how to build agentic workflows with conditional logic.

Session Expires Mid-Task

Symptom: Claude hits a login wall partway through a long automation run.

Fix: Save session state at the start of any task that requires authentication. Implement a check at the beginning of each sub-task that verifies the session is still valid before proceeding.

Where Remy Fits

Claude Code + Playwright is a powerful combination for browser automation. But it’s still a tool you configure and manage manually — MCP server setup, prompt engineering, session management, token control, scheduling. That’s real work, especially when you want to turn a one-off automation into something that runs reliably over time.

Remy approaches this from a different angle. Instead of configuring tools and writing prompts, you describe the application in a spec — annotated prose that compiles into a full-stack app with a real backend, database, and auth system. If your browser automation work is part of a larger product (a monitoring dashboard, a data pipeline with a UI, a QA reporting tool), Remy handles the application layer so you’re not stitching together infrastructure from scratch.

The spec is the source of truth. The code — including whatever automation logic connects to Playwright — is compiled output. As requirements change, you update the spec, not the codebase.

If you want to see what this looks like in practice, try Remy at mindstudio.ai/remy.

Frequently Asked Questions

Does Claude Code have built-in browser access without Playwright?

Not through the standard setup. Claude Code can read and write files, run terminal commands, and call MCP servers — but it doesn’t have direct browser control by default. Playwright (via its MCP server) is what gives it that capability. There are also computer use approaches that work at the pixel level, but Playwright’s structured DOM access is faster and more reliable for most automation tasks.

Can I use Playwright MCP with Claude Code in a CI/CD pipeline?

Yes. The setup works in headless mode on any server with Node.js installed. The main consideration is that Claude Code needs an API key and the MCP server needs to be started before Claude runs. For CI environments, you’d typically start the MCP server as a background process, run Claude Code in headless/non-interactive mode, and capture the output for your pipeline.

What’s the difference between Playwright MCP and Claude Computer Use?

Playwright MCP gives Claude structured browser control through the DOM — it can read element attributes, wait for specific selectors, and interact with the page programmatically. Claude Computer Use works through screenshots and mouse/keyboard simulation, treating the browser like a visual interface. Playwright is more precise and efficient for web-specific tasks. Computer use is more flexible for anything that runs on a desktop, including apps outside the browser. For web automation specifically, Playwright is usually the right choice.

Is Playwright MCP safe to use with real credentials?

It’s as safe as any other automation that handles credentials — which means you should follow standard security practices. Store passwords and API keys in environment variables, not hardcoded in prompts. Use dedicated automation accounts with limited permissions where possible. Be aware that Claude will include credentials in its tool calls if you provide them in the prompt, so treat your Claude Code sessions accordingly. Don’t share session logs or terminal output that includes credential strings.

Can I run the Playwright MCP server on a remote machine?

Yes. The MCP server can run anywhere and communicate over a socket connection. For remote setups, you’d configure Claude Code to connect to the server at its IP and port rather than launching it locally. This is useful if you want the browser running on a cloud VM with a stable IP address — helpful for sites that geo-restrict access or track IPs. The remote desktop automation approach with Dispatch covers a similar architecture for computer use, and the same principles apply.

How do I handle sites that require JavaScript-heavy interactions?

Playwright waits for page load events by default, but some SPAs and dynamic apps need more specific wait conditions. You can tell Claude to “wait for the results table to appear” or “wait until the loading spinner disappears” — Playwright’s wait_for_selector tool handles this. For pages that trigger data loads on scroll, you can instruct Claude to scroll to trigger them before extracting data. If a site is particularly difficult, checking the web scraping token reduction techniques may also help since complex pages tend to be expensive to process.

Key Takeaways

Claude Code + Playwright CLI connects Claude to a real browser through an MCP server, giving it structured DOM access rather than pixel-level control.
Setup takes about 10 minutes: install @playwright/mcp, add it to your Claude Code MCP config, and verify the connection.
The three strongest use cases are QA testing, web scraping of dynamic pages, and tasks that require authenticated sessions.
Token costs are manageable if you’re specific in prompts, limit screenshots, and set clear stop conditions.
Common problems — connection failures, bot detection, session expiry — all have known fixes.
For teams building products around browser automation, Remy handles the application layer so the automation logic fits into a real full-stack system rather than a collection of scripts.