Playwright Browser Automation MCP server

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

Installation

Using NPX

You can configure the Playwright MCP server using NPX in your MCP configuration:

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

Installing in VS Code

You can install the Playwright MCP server in VS Code using the command line:

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

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

After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.

Using Docker

Docker implementation currently only supports headless chromium:

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "mcp/playwright"]
    }
  }
}

To build the Docker image yourself:

docker build -t mcp/playwright .

Server Configuration

Command Line Options

The Playwright MCP server supports the following options:

• --browser <browser>: Choose which browser to use (chrome, firefox, webkit, msedge, chrome-beta, etc.)
• --caps <caps>: Comma-separated list of capabilities to enable (tabs, pdf, history, wait, files, install)
• --cdp-endpoint <endpoint>: CDP endpoint to connect to
• --executable-path <path>: Path to the browser executable
• --headless: Run browser in headless mode (headed by default)
• --port <port>: Port to listen on for SSE transport
• --host <host>: Host to bind server to (default: localhost)
• --user-data-dir <path>: Path to the user data directory
• --vision: Run server that uses screenshots instead of accessibility snapshots

Running in Headless Mode

For background or batch operations without a GUI:

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

Running on Remote Systems

For systems without a display or when running in a remote environment:

npx @playwright/mcp@latest --port 8931 --host 0.0.0.0

In your MCP client config, use:

{
  "mcpServers": {
    "playwright": {
      "url": "http://{$server-ip}:8931/sse"
    }
  }
}

Tool Modes

The server offers two modes:

1. Snapshot Mode (default): Uses accessibility snapshots for better performance
2. Vision Mode: Uses screenshots for visual-based interactions

To use Vision Mode:

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

Using the MCP Tools

Snapshot-based Interactions

Basic Page Operations

• Capture a snapshot:

  • Tool: browser_snapshot
  • No parameters required

• Navigate to a URL:

  • Tool: browser_navigate
  • Parameters: url (string)

• Take a screenshot:

  • Tool: browser_take_screenshot
  • Parameters:
    • raw (boolean, optional): Return without compression if true
    • element (string, optional): Element description
    • ref (string, optional): Element reference

Element Interactions

• Click an element:

  • Tool: browser_click
  • Parameters:
    • element (string): Human-readable element description
    • ref (string): Element reference from snapshot

• Hover over an element:

  • Tool: browser_hover
  • Parameters:
    • element (string): Element description
    • ref (string): Element reference

• Type text into an element:

  • Tool: browser_type
  • Parameters:
    • element (string): Element description
    • ref (string): Element reference
    • text (string): Text to type
    • submit (boolean, optional): Whether to press Enter after typing
    • slowly (boolean, optional): Whether to type one character at a time

• Select dropdown options:

  • Tool: browser_select_option
  • Parameters:
    • element (string): Element description
    • ref (string): Element reference
    • values (array): Values to select

• Drag and drop:

  • Tool: browser_drag
  • Parameters:
    • startElement (string): Source element description
    • startRef (string): Source element reference
    • endElement (string): Target element description
    • endRef (string): Target element reference

Vision-based Interactions

• Capture screen:

  • Tool: browser_screen_capture
  • No parameters required

• Click at coordinates:

  • Tool: browser_screen_click
  • Parameters:
    • element (string): Element description
    • x (number): X coordinate
    • y (number): Y coordinate

• Type text:

  • Tool: browser_screen_type
  • Parameters:
    • text (string): Text to type
    • submit (boolean, optional): Whether to press Enter after

Tab Management

• List tabs:

  • Tool: browser_tab_list
  • No parameters required

• Create new tab:

  • Tool: browser_tab_new
  • Parameters:
    • url (string, optional): URL to navigate to

• Select a tab:

  • Tool: browser_tab_select
  • Parameters:
    • index (number): Tab index

• Close a tab:

  • Tool: browser_tab_close
  • Parameters:
    • index (number, optional): Tab index to close

Additional Utilities

• Press a key:

  • Tool: browser_press_key
  • Parameters:
    • key (string): Key name (e.g., ArrowLeft or a)

• Upload files:

  • Tool: browser_file_upload
  • Parameters:
    • paths (array): Absolute paths to files

• Wait for a specified time:

  • Tool: browser_wait
  • Parameters:
    • time (number): Time in seconds

• Resize browser window:

  • Tool: browser_resize
  • Parameters:
    • width (number): Window width
    • height (number): Window height

• Save page as PDF:

  • Tool: browser_pdf_save
  • No parameters required

• Handle dialogs:

  • Tool: browser_handle_dialog
  • Parameters:
    • accept (boolean): Whether to accept the dialog
    • promptText (string, optional): Text for prompt dialogs

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.