Playwright Browser Automation MCP server for AI agents

The Playwright MCP server provides browser automation capabilities using Playwright, enabling LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Installation

To install the Playwright MCP server, you'll need Node.js 18 or newer and a compatible MCP client like VS Code, Cursor, Claude Desktop, or Goose.

Basic Installation

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

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

Client-Specific Installation

VS Code

You can install the server manually by going to VS Code settings and adding the MCP server with the standard configuration above. Alternatively, use the VS Code CLI:

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

Cursor

Go to Cursor Settings → MCP → Add new MCP Server. Name it as you prefer, use command type with the command npx @playwright/mcp.

Goose

Go to Advanced settings → Extensions → Add custom extension. Name it as you prefer, use type STDIO, and set the command to npx @playwright/mcp.

Claude Desktop

Follow the MCP install guide at modelcontextprotocol.io/quickstart/user, using the standard config above.

Configuration Options

The Playwright MCP server supports various configuration options that can be added to the args list in your configuration:

--allowed-origins <origins>   # semicolon-separated list of origins to allow
--blocked-origins <origins>   # semicolon-separated list of origins to block
--block-service-workers       # block service workers
--browser <browser>           # browser to use (chrome, firefox, webkit, msedge)
--caps <caps>                 # additional capabilities (vision, pdf)
--cdp-endpoint <endpoint>     # CDP endpoint to connect to
--config <path>               # path to configuration file
--device <device>             # device to emulate, e.g., "iPhone 15"
--executable-path <path>      # path to browser executable
--extension                   # connect to running browser instance
--headless                    # run browser in headless mode
--host <host>                 # host to bind server to
--ignore-https-errors         # ignore https errors
--isolated                    # keep browser profile in memory
--image-responses <mode>      # whether to send image responses
--no-sandbox                  # disable sandbox
--output-dir <path>           # directory for output files
--port <port>                 # port to listen on for SSE transport
--proxy-bypass <bypass>       # comma-separated domains to bypass proxy
--proxy-server <proxy>        # specify proxy server
--save-session                # save Playwright MCP session
--save-trace                  # save Playwright Trace
--storage-state <path>        # path to storage state file
--user-agent <ua string>      # specify user agent string
--user-data-dir <path>        # path to user data directory
--viewport-size <size>        # browser viewport size in pixels

User Profiles

The server can run with different profile modes:

Persistent Profile (Default)

All login information is stored in a persistent profile. You can specify a custom location with --user-data-dir.

Default locations:

Windows: %USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile
macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-profile
Linux: ~/.cache/ms-playwright/mcp-{channel}-profile

Isolated Mode

In isolated mode, each session starts with a clean profile:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state={path/to/storage.json}"
      ]
    }
  }
}

Using a Configuration File

For more complex setups, you can use a JSON configuration file:

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

The configuration file supports browser settings, server options, capabilities, and network configurations.

Running as a Standalone Server

For environments without a display or for worker processes, run the MCP server with the --port flag:

npx @playwright/mcp@latest --port 8931

Then configure your MCP client to connect to the HTTP endpoint:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Available Tools

The Playwright MCP server provides various tools for browser automation:

Core Automation

browser_click: Click on web page elements
browser_navigate: Navigate to a URL
browser_type: Type text into form fields
browser_snapshot: Capture page structure
browser_take_screenshot: Take screenshots
browser_evaluate: Execute JavaScript code
browser_hover: Hover over elements
browser_press_key: Press keyboard keys
browser_wait_for: Wait for text or time

Tab Management

browser_tab_new: Open a new tab
browser_tab_close: Close a tab
browser_tab_list: List open tabs
browser_tab_select: Switch between tabs

Additional Capabilities

PDF generation: Save pages as PDF files (requires --caps=pdf)
Coordinate-based interactions: Interact with specific screen coordinates (requires --caps=vision)

Each tool accepts specific parameters and can be used by the connected LLM to interact with web pages in a structured, deterministic way.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect