Playwright MCP server

 Introduction

The Playwright MCP server provides browser automation capabilities through the Model Context Protocol, enabling LLMs to interact with web pages using structured accessibility snapshots. It works with VS Code, Cursor, Windsurf, Claude Desktop, and any other MCP client — no vision models required.

Prerequisites

Before you begin, make sure you have the following installed:

Node.js 20 or newer

An MCP client: VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, or similar

Getting Started

Installation

Add the Playwright MCP server to your client using the standard configuration:

{

  "mcpServers": {

    "playwright": {

      "command": "npx",

      "args": [

        "@playwright/mcp@latest"

      ]

    }

  }

}

VS Code

Click one of the buttons below to install directly:

Install in VS Code Install in VS Code Insiders

Or install via the VS Code CLI:

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

Cursor

Install in Cursor

Or go to Cursor Settings → MCP → Add new MCP Server and use command type with npx @playwright/mcp@latest.

Claude Code

claude mcp add playwright npx @playwright/mcp@latest

Claude Desktop

Follow the MCP install guide and use the standard config above.

Other clients

The standard configuration works with most MCP clients, including Windsurf, Cline, Goose, Kiro, Codex, Copilot CLI, and others. Consult your client's MCP documentation for where to place the config.

First interaction

Once the server is connected, ask your AI assistant to interact with a web page:

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

The assistant will use Playwright MCP tools to open the browser, navigate to the page, and interact with elements — all through structured accessibility snapshots rather than screenshots.

Core Features

Accessibility snapshots

Playwright MCP operates on the page's accessibility tree, not pixels. When a tool runs, it returns a structured snapshot showing the page elements, their roles, and text content. The LLM uses element references from these snapshots to interact with the page:

- heading "todos" [level=1]

- textbox "What needs to be done?" [ref=e5]

- listitem:

  - checkbox "Toggle Todo" [ref=e10]

  - text: "Buy groceries"

The LLM reads this snapshot and uses ref=e5 to type into the textbox or ref=e10 to check the checkbox.

Interacting with pages

Playwright MCP provides tools for all common browser interactions:

Navigation: Open URLs, go back/forward, reload pages.

Clicking and typing: Click elements, type text, fill forms, select dropdowns.

Screenshots: Capture the current page or specific elements for visual verification.

Keyboard and mouse: Press keys, hover, drag and drop.

Dialogs: Accept or dismiss browser dialogs.

Tabs: Create, close, and switch between browser tabs.

Running Playwright code

For complex interactions that go beyond individual tool calls, use the browser_run_code_unsafe tool to execute Playwright scripts directly. This tool runs arbitrary JavaScript in the Playwright server process and is RCE-equivalent — only enable it for trusted MCP clients:

Run this Playwright code to verify the todo count:

async (page) => {

  const count = await page.getByTestId('todo-count').textContent();

  return count;

}

Network monitoring and mocking

Inspect network traffic and mock API responses:

View network requests: List all requests made since page load.

Mock routes: Set up URL pattern matching to return custom responses.

Console messages: Access browser console output for debugging.

Storage state

Save and restore browser state including cookies and localStorage:

Save state: Persist authentication and session data to a file.

Restore state: Load previously saved state into a new session.

Cookie management: List, get, set, and delete individual cookies.

Configuration

Headed mode

By default, Playwright MCP runs the browser in headed mode so you can see what's happening. To run headless:

{

  "mcpServers": {

    "playwright": {

      "command": "npx",

      "args": [

        "@playwright/mcp@latest",

        "--headless"

      ]

    }

  }

}

Browser selection

Choose which browser to use:

{

  "mcpServers": {

    "playwright": {

      "command": "npx",

      "args": [

        "@playwright/mcp@latest",

        "--browser=firefox"

      ]

    }

  }

}

Supported values: chrome, firefox, webkit, msedge.

User profile

Playwright MCP supports three profile modes:

Persistent (default): Login state and cookies are preserved between sessions. The profile is stored in ms-playwright/mcp-{channel}-{workspace-hash} in your platform's cache directory, so different projects get separate profiles automatically. Override with --user-data-dir.

Isolated: Each session starts fresh. Pass --isolated to enable. You can load initial state with --storage-state.

Browser extension: Connect to your existing browser tabs with the Playwright Extension. Pass --extension to enable.

Configuration file

For advanced configuration, use a JSON config file:

npx @playwright/mcp@latest --config path/to/config.json

The config file supports browser options, context options, network rules, timeouts, and more. See the Playwright MCP repository for the full schema.

Standalone server

When running a headed browser on a system without a display or from IDE worker processes, start the MCP server separately with HTTP transport:

npx @playwright/mcp@latest --port 8931

HTTP sessions use a five-second heartbeat timeout. If your MCP client or proxy does not answer server-initiated pings, set PLAYWRIGHT_MCP_PING_TIMEOUT_MS to a longer timeout in milliseconds. Set it to 0 to disable the heartbeat.

Then point your MCP client to the HTTP endpoint:

{

  "mcpServers": {

    "playwright": {

      "url": "http://localhost:8931/mcp"

    }

  }

}

Quick Reference

Action How to do it

Install server Add standard config to your MCP client

Navigate to a page Ask: "Go to https://example.com"

Click an element Ask: "Click the Submit button"

Fill a form Ask: "Fill in the email field with test@example.com"

Take a screenshot Ask: "Take a screenshot of the page"

Run Playwright code Ask: "Run this Playwright code: ..."

Mock an API Ask: "Mock the /api/users endpoint to return ..."

Use headed mode Default. Pass --headless to disable

Choose a browser Pass --browser=firefox in args

How to map Claude extension features to goals ?

 

This is best overview of how to match the goal and the features that Claude provides. 

How to extend the claude functionalities? What are diferent ways

Extensions plug into different parts of the agentic loop:

CLAUDE.md adds persistent context Claude sees every session

Skills add reusable knowledge and invocable workflows

Code intelligence connects Claude to a language server for symbol-level navigation and live type errors

MCP connects Claude to external services and tools

Subagents run their own loops in isolated context, returning summaries

Agent teams coordinate multiple independent sessions with peer-to-peer messaging, plus a shared task list for agents that have the Task tools

Hooks run your script, HTTP request, prompt, or subagent when Claude Code reaches a lifecycle event

Plugins and marketplaces package and distribute these features

Skills are the most flexible extension. A skill is a markdown file containing knowledge, workflows, or instructions. You can invoke skills with a command like /deploy, or Claude can load them automatically when relevant. Skills can run in your current conversation or in an isolated context via subagents.

How to work effectively with Claude Code?

 Work effectively with Claude Code

These tips help you get better results from Claude Code.

​

Ask Claude Code for help

Claude Code can teach you how to use it. Ask questions like “how do I set up hooks?” or “what’s the best way to structure my CLAUDE.md?” and Claude will explain.

Built-in commands also guide you through setup:

/init walks you through creating a CLAUDE.md for your project

/doctor runs a setup checkup that diagnoses installation and configuration issues and can fix them

​

It’s a conversation

Claude Code is conversational. You don’t need perfect prompts. Start with what you want, then refine:

Fix the login bug

[Claude investigates, tries something]

That's not quite right. The issue is in the session handling.

[Claude adjusts approach]

When the first attempt isn’t right, you don’t start over. You iterate.

​

Interrupt and steer

You can redirect Claude at any point without waiting for the turn to finish or starting over:

Press Esc to stop Claude immediately. The running tool call is canceled and Claude waits for your next instruction.

Type a correction and press Enter to send it without stopping the running tool. Claude reads it as soon as the current action completes and adjusts before deciding its next step.

​

Be specific upfront

The more precise your initial prompt, the fewer corrections you’ll need. Reference specific files, mention constraints, and point to example patterns.

The checkout flow is broken for users with expired cards.

Check src/payments/ for the issue, especially token refresh.

Write a failing test first, then fix it.

Vague prompts work, but you’ll spend more time steering. Specific prompts like the one above often succeed on the first attempt.

​

Give Claude something to verify against

Claude performs better when it can check its own work. Include test cases, paste screenshots of expected UI, or define the output you want.

Implement validateEmail. Test cases: 'user@example.com' → true,

'invalid' → false, 'user@.com' → false. Run the tests after.

For visual work, paste a screenshot of the design and ask Claude to compare its implementation against it.

​

Explore before implementing

For complex problems, separate research from coding. Use plan mode (Shift+Tab twice) to analyze the codebase first:

Read src/auth/ and understand how we handle sessions.

Then create a plan for adding OAuth support.

Review the plan, refine it through conversation, then let Claude implement. This two-phase approach produces better results than jumping straight to code.

​

Delegate, don’t dictate

Think of delegating to a capable colleague. Give context and direction, then trust Claude to figure out the details:

The checkout flow is broken for users with expired cards.

The relevant code is in src/payments/. Can you investigate and fix it?

LLM Watermarking

 Future Claude models will generate text that contains a watermark. This is a way of determining the likelihood that Claude was involved in writing the text, and we, along with several other major AI providers, are implementing this change to comply with the EU AI Act.

In this article, we share answers to some of the questions we’ve received about how our chosen watermarking method works, whether it affects Claude’s outputs, and why we’re making this change. To summarize:

We use a method of watermarking that does not have any practical impact on the quality or content of Claude’s outputs;

The difference between watermarked and un-watermarked text will not be distinguishable to readers;

Nothing is added to the text and there are no hidden characters;

Watermarking doesn’t require extra tokens, and will not be more expensive;

Watermarking carries no identifying information and can’t be traced to a specific person, organization, or chat;

Watermarking won’t be specific to Claude. As of August 2, the EU requires AI providers serving its market to mark AI-generated content. Other major model developers have signed the same Code of Practice and will be implementing their own watermarks.

What is watermarking?

Large language models like Claude work by generating one word at a time. Each time the model decides on the next word, it chooses among a list of potential candidates, ultimately selecting the most sensible or likely based on the preceding text. Take the sentence “The weather today was cold and…”. The next word is very unlikely to be “sugary.” But it is quite likely to be “overcast” or “grey.” Under most circumstances, it doesn’t matter much to the reader which of these latter two words the model ultimately chooses—the meaning of the sentence is largely the same either way. In cases like this, the choice is settled by a random number.

Watermarking uses low-stakes choices like these—which occur many times over a piece of generated text—to leave a pattern in Claude’s responses. That pattern is undetectable to the reader, but is detectable to anyone who has a key that encodes it. When watermarking is used, choices are still made at random, but the source of the randomness is different. Instead of using an arbitrary random number generator to pick the next word, watermarking uses the key and a few words that come before to settle what word the model should pick. That is, the words that Claude picks are still random, but now, one can check the sequence of words and see if it’s consistent with the choices Claude would make if it was using the key. If it is, one can assign a probability that the text was generated by Claude.

Importantly, it isn’t that the model will now always be biased toward overcast or grey. Just as with non-watermarked text, overcast might be selected in one sentence, grey in the next, depending on the words that came before. And it’s not the case that the watermarking method pushes Claude to choose a word it wouldn’t have considered anyway (for instance, it wouldn’t make Claude pick a word like “nubilous”—an obscure1 synonym for overcast or grey that Claude almost certainly wouldn’t use under normal circumstances).

Details about Claude Context Window, Subagents and Memory

 The context window

Claude’s context window holds your conversation history, file contents, command outputs, CLAUDE.md, auto memory, loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run /context to see what’s using space.

For an interactive walkthrough of what loads and when, see Explore the context window.

​

When context fills up

Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on conversation history.

To control what’s preserved during compaction, add a “Compact Instructions” section to CLAUDE.md or run /compact with a focus (like /compact focus on the API changes).

If a single file or tool output is so large that context refills immediately after each summary, Claude Code stops auto-compacting after a few attempts and shows an error instead of looping. See Auto-compaction stops with a thrashing error for recovery steps.

Run /context to see what’s using space. MCP tool definitions are deferred by default and loaded on demand via tool search, so only tool names consume context until Claude uses a specific tool. Run /mcp to check per-server costs.

​

Manage context with skills and subagents

Beyond compaction, you can use other features to control what loads into context.

Skills load on demand. Claude sees skill descriptions at session start, but the full content only loads when a skill is used. For skills you invoke manually, set disable-model-invocation: true to keep descriptions out of context until you need them. For skills you didn’t write, use skillOverrides to do the same from settings.

Subagents get their own fresh context, completely separate from your main conversation. Their work doesn’t bloat your context. When done, they return a summary. This isolation is why subagents help with long sessions.

See context costs for what each feature costs, and reduce token usage for tips on managing context.

​

Stay safe with checkpoints and permissions

Claude has two safety mechanisms: checkpoints let you undo file changes, and permissions control what Claude can do without asking.

​

Undo changes with checkpoints

File edits are reversible. Before Claude edits a file, it snapshots the current contents. If something goes wrong, press Esc twice to rewind to a previous state, or ask Claude to undo.

Checkpoints are separate from git and remain available when you resume a conversation. They only cover file changes, and a restore skips symlinked and hard-linked files. Actions that affect remote systems (databases, APIs, deployments) can’t be checkpointed, which is why Claude asks before running commands with external side effects.

​

Control what Claude can do

Press Shift+Tab to cycle through permission modes:

Manual: Claude asks before file edits and shell commands

Accept edits: Claude edits files and runs common filesystem commands like mkdir and mv without asking, still asks for other commands

Plan: Claude explores and proposes a plan without editing your source files

Auto: Claude evaluates all actions with background safety checks

You can also allow specific commands in .claude/settings.json so Claude doesn’t ask each time. This is useful for trusted commands like npm test or git status. Settings can be scoped from organization-wide policies down to personal preferences. See Permissions for details.

details about Claude Models , Claude Tools, Memory , Environments and Interfaces

 Claude Models 

=============

Claude Code uses Claude models to understand your code and reason about tasks. Claude can read code in any language, understand how components connect, and figure out what needs to change to accomplish your goal. For complex tasks, it breaks work into steps, executes them, and adjusts based on what it learns.

Multiple models are available with different tradeoffs. Sonnet handles most coding tasks well. Opus provides stronger reasoning for complex architectural decisions. Switch with /model during a session or start with claude --model <name>.

Claude Tools

===========

Tools are what make Claude Code agentic. Without tools, Claude can only respond with text. With tools, Claude can act: read your code, edit files, run commands, search the web, and interact with external services. Each tool use returns information that feeds back into the loop, informing Claude’s next decision.

The built-in tools generally fall into five categories, each representing a different kind of agency.

Category What Claude can do

File operations Read files, edit code, create new files, rename and reorganize

Search Find files by pattern, search content with regex, explore codebases

Execution Run shell commands, start servers, run tests, use git

Web Search the web, fetch documentation, look up error messages

Code intelligence See type errors and warnings after edits, jump to definitions, find references (requires code intelligence plugins)

Claude chooses which tools to use based on your prompt and what it learns along the way. When you say “fix the failing tests,” Claude might:

Run the test suite to see what’s failing

Read the error output

Search for the relevant source files

Read those files to understand the code

Edit the files to fix the issue

Run the tests again to verify

Each tool use gives Claude new information that informs the next step. This is the agentic loop in action.

Extending the base capabilities: The built-in tools are the foundation. You can extend what Claude knows with skills, connect to external services with MCP, automate workflows with hooks, and offload tasks to subagents. These extensions form a layer on top of the core agentic loop. 

What Claude can access

When you run claude in a directory, Claude Code gains access to:

Your project. Files in your directory and subdirectories, plus files elsewhere with your permission.

Your terminal. Any command you could run: build tools, git, package managers, system utilities, scripts. If you can do it from the command line, Claude can too.

Your git state. Current branch, uncommitted changes, and recent commit history.

Your CLAUDE.md. A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session.

Auto memory. Learnings Claude saves automatically as you work, like project patterns and your preferences. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of each session.

Extensions you configure. MCP servers for external services, skills for workflows, subagents for delegated work, and Claude in Chrome for browser interaction.

Because Claude sees your whole project, it can work across it. When you ask Claude to “fix the authentication bug,” it searches for relevant files, reads multiple files to understand context, makes coordinated edits across them, runs tests to verify the fix, and commits the changes if you ask. This is different from inline code assistants that only see the current file.

Environments and interfaces

The agentic loop, tools, and capabilities described above are the same everywhere you use Claude Code. What changes is where the code executes and how you interact with it.

​

Execution environments

Claude Code runs in three environments, each with different tradeoffs for where your code executes.

Environment Where code runs Use case

Local Your machine Default. Full access to your files, tools, and environment

Cloud Anthropic-managed VMs, or self-hosted environments your organization operates Offload tasks, work on repos you don’t have locally

Remote Control Your machine, controlled from a browser Use the web UI while execution and your files stay local

Work with sessions

Claude Code saves your conversation locally as you work. Each message, tool use, and result is written to a plaintext JSONL file under ~/.claude/projects/, which enables rewinding, resuming, and forking sessions. Before Claude makes code changes, it also snapshots the affected files so you can revert if needed. For paths, retention, and how to clear this data, see application data in ~/.claude.

Sessions are independent. Each new session starts with a fresh context window, without the conversation history from previous sessions. Claude can persist learnings across sessions using auto memory, and you can add your own persistent instructions in CLAUDE.md.

​

Work across branches

Each Claude Code conversation is a session tied to your current directory. The /resume picker shows sessions from the current worktree by default, with keyboard shortcuts to widen the list to other worktrees or projects. See Manage sessions for the full list of picker shortcuts and how name resolution works.

Claude sees your current branch’s files. When you switch branches, Claude sees the new branch’s files, but your conversation history stays the same. Claude remembers what you discussed even after switching.

Since sessions are tied to directories, you can run parallel Claude sessions by using git worktrees, which create separate directories for individual branches.

​