Installation

Complete installation guide for Playwright MCP across all supported MCP clients

Requirements

Before installing Playwright MCP, ensure you have:

• Node.js 18 or newer installed on your system
• An MCP-compatible client (VS Code, Cursor, Claude Desktop, etc.)

On first run, Playwright will automatically download browser binaries. This is a one-time setup that may take a few minutes depending on your connection speed.

Standard Configuration

Most MCP clients use this standard JSON configuration:

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

Client-Specific Installation

Choose your MCP client below for detailed installation instructions:

VS Code

VS Code / VS Code Insiders

One-Click Install

Click the button to install directly:

Install in VS Code

Manual Installation

1. Open VS Code Settings
2. Search for “MCP”
3. Add the standard configuration above

CLI Installation

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

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

Cursor

Cursor

One-Click Install

Install in Cursor

Manual Installation

1. Go to Cursor Settings → MCP → Add new MCP Server
2. Choose a name for the server (e.g., “playwright”)
3. Select command type
4. Enter command: npx @playwright/mcp@latest
5. Click Edit to verify or add arguments
6. Save your configuration

Claude Desktop

Claude Desktop

1. Follow the official MCP quickstart guide
2. Add the standard configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

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

3. Restart Claude Desktop

Windsurf

Windsurf

1. Follow the Windsurf MCP documentation
2. Add the standard configuration to your Windsurf config file
3. Restart Windsurf to activate the server

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

Goose

Goose

One-Click Install

Install in Goose

Manual Installation

1. Open Goose
2. Go to Advanced settings → Extensions → Add custom extension
3. Enter a name (e.g., “Playwright”)
4. Select type: STDIO
5. Set command: npx @playwright/mcp
6. Click “Add Extension”

Cline

Cline

Follow the Configuring MCP Servers documentation.

Add the following to your cline_mcp_settings.json file:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ],
      "disabled": false
    }
  }
}

The -y flag automatically accepts the npx prompt to install the package.

More Clients

Amp

Settings UI

Add via the Amp VS Code extension settings screen or update settings.json:

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

CLI

amp mcp add playwright -- npx @playwright/mcp@latest

Antigravity

Add via Antigravity settings or update your configuration file:

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

Claude Code

Use the Claude Code CLI:

claude mcp add playwright npx @playwright/mcp@latest

Codex

CLI

codex mcp add playwright npx "@playwright/mcp@latest"

Configuration File

Edit ~/.codex/config.toml:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

See Codex MCP documentation for more details.

Copilot

Interactive Setup

/mcp add

Configuration File

Edit ~/.copilot/mcp-config.json:

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

See Copilot CLI documentation for more information.

Factory

CLI

droid mcp add playwright "npx @playwright/mcp@latest"

Interactive UI

Type /mcp within Factory droid to open the interactive UI for managing MCP servers.

See Factory MCP documentation for more details.

Gemini CLI

Follow the MCP install guide and use the standard configuration.

Kiro

Follow the MCP Servers documentation.

Example configuration in .kiro/settings/mcp.json:

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

LM Studio

One-Click Install

Install in LM Studio

Manual Installation

1. Open LM Studio
2. Go to Program in the right sidebar
3. Click Install → Edit mcp.json
4. Add the standard configuration

opencode

Follow the MCP Servers documentation.

Example configuration in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@playwright/mcp@latest"
      ],
      "enabled": true
    }
  }
}

Qodo Gen

1. Open the Qodo Gen chat panel in VSCode or IntelliJ
2. Click “Connect more tools”
3. Click ”+ Add new MCP”
4. Paste the standard configuration
5. Click “Save”

Warp

Settings UI

1. Go to Settings → AI → Manage MCP Servers → + Add
2. Follow the add an MCP Server guide
3. Use the standard configuration

Slash Command

Type /add-mcp in the Warp prompt and paste:

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

Advanced Installation

Standalone HTTP Server

For systems without a display or when running from IDE worker processes, run Playwright MCP as a standalone HTTP server:

npx @playwright/mcp@latest --port 8931

Then configure your MCP client to connect via HTTP:

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

Docker Installation

The Docker implementation currently only supports headless Chromium.

MCP Client Spawns Container

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

Long-Lived Service Container

Run the container as a persistent service:

docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  --name playwright \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0

The server will listen on port 8931 and can be reached by any MCP client using the HTTP URL configuration above.

Build Docker Image Locally

docker build -t mcr.microsoft.com/playwright/mcp .

Verification

After installation, verify that Playwright MCP is working:

1. Restart your MCP client to load the new configuration
2. Check for available tools - You should see browser automation tools like browser_navigate, browser_snapshot, etc.
3. Test basic navigation - Try asking your LLM to navigate to a simple website

If tools aren’t appearing, check your client’s logs for connection errors or configuration issues.

Troubleshooting

Browser Not Installed

On first run, Playwright downloads browser binaries automatically. If you see errors about missing browsers:

npx playwright install

Or use the browser_install tool from within your MCP client.

Permission Issues

If you encounter permission errors:

• Ensure Node.js is properly installed and in your PATH
• Try running with explicit permissions: npx --yes @playwright/mcp@latest
• On Linux, you may need to install additional dependencies

Connection Timeout

If the MCP client can’t connect to Playwright:

• Verify Node.js version is 18 or newer: node --version
• Check that npx can execute: npx --version
• Try increasing timeout in your client config (if supported)

Headless Mode Issues

If running on a system without a display:

• Use --headless flag in your configuration
• Or run as a standalone HTTP server (see Advanced Installation)

Next Steps

Quick Start

Create your first automation with Playwright MCP

Configuration

Learn about all configuration options and customization