> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/playwright-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.)

<Note>
  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.
</Note>

## Standard Configuration

Most MCP clients use this standard JSON configuration:

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}
```

## Client-Specific Installation

Choose your MCP client below for detailed installation instructions:

<Tabs>
  <Tab title="VS Code">
    ### VS Code / VS Code Insiders

    #### One-Click Install

    Click the button to install directly:

    <a href="https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D" target="_blank">
      Install in VS Code
    </a>

    #### Manual Installation

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

    #### CLI Installation

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

    <Tip>
      After installation, the Playwright MCP server will be available for use with GitHub Copilot in VS Code.
    </Tip>
  </Tab>

  <Tab title="Cursor">
    ### Cursor

    #### One-Click Install

    <a href="https://cursor.com/en/install-mcp?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D" target="_blank">
      Install in Cursor
    </a>

    #### 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
  </Tab>

  <Tab title="Claude Desktop">
    ### Claude Desktop

    1. Follow the official [MCP quickstart guide](https://modelcontextprotocol.io/quickstart/user)
    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`

    ```json theme={null}
    {
      "mcpServers": {
        "playwright": {
          "command": "npx",
          "args": [
            "@playwright/mcp@latest"
          ]
        }
      }
    }
    ```

    3. Restart Claude Desktop
  </Tab>

  <Tab title="Windsurf">
    ### Windsurf

    1. Follow the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp)
    2. Add the standard configuration to your Windsurf config file
    3. Restart Windsurf to activate the server

    ```json theme={null}
    {
      "mcpServers": {
        "playwright": {
          "command": "npx",
          "args": [
            "@playwright/mcp@latest"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Goose">
    ### Goose

    #### One-Click Install

    <a href="https://block.github.io/goose/extension?cmd=npx&arg=%40playwright%2Fmcp%40latest&id=playwright&name=Playwright&description=Interact%20with%20web%20pages%20through%20structured%20accessibility%20snapshots%20using%20Playwright" target="_blank">
      Install in Goose
    </a>

    #### 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"
  </Tab>

  <Tab title="Cline">
    ### Cline

    Follow the [Configuring MCP Servers](https://docs.cline.bot/mcp/configuring-mcp-servers) documentation.

    Add the following to your `cline_mcp_settings.json` file:

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

    <Note>
      The `-y` flag automatically accepts the npx prompt to install the package.
    </Note>
  </Tab>
</Tabs>

<Accordion title="More Clients">
  <AccordionGroup>
    <Accordion title="Amp">
      #### Settings UI

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

      ```json theme={null}
      "amp.mcpServers": {
        "playwright": {
          "command": "npx",
          "args": [
            "@playwright/mcp@latest"
          ]
        }
      }
      ```

      #### CLI

      ```bash theme={null}
      amp mcp add playwright -- npx @playwright/mcp@latest
      ```
    </Accordion>

    <Accordion title="Antigravity">
      Add via Antigravity settings or update your configuration file:

      ```json theme={null}
      {
        "mcpServers": {
          "playwright": {
            "command": "npx",
            "args": [
              "@playwright/mcp@latest"
            ]
          }
        }
      }
      ```
    </Accordion>

    <Accordion title="Claude Code">
      Use the Claude Code CLI:

      ```bash theme={null}
      claude mcp add playwright npx @playwright/mcp@latest
      ```
    </Accordion>

    <Accordion title="Codex">
      #### CLI

      ```bash theme={null}
      codex mcp add playwright npx "@playwright/mcp@latest"
      ```

      #### Configuration File

      Edit `~/.codex/config.toml`:

      ```toml theme={null}
      [mcp_servers.playwright]
      command = "npx"
      args = ["@playwright/mcp@latest"]
      ```

      See [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers) for more details.
    </Accordion>

    <Accordion title="Copilot">
      #### Interactive Setup

      ```bash theme={null}
      /mcp add
      ```

      #### Configuration File

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

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

      See [Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) for more information.
    </Accordion>

    <Accordion title="Factory">
      #### CLI

      ```bash theme={null}
      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](https://docs.factory.ai/cli/configuration/mcp) for more details.
    </Accordion>

    <Accordion title="Gemini CLI">
      Follow the [MCP install guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson) and use the standard configuration.
    </Accordion>

    <Accordion title="Kiro">
      Follow the [MCP Servers documentation](https://kiro.dev/docs/mcp/).

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

      ```json theme={null}
      {
        "mcpServers": {
          "playwright": {
            "command": "npx",
            "args": [
              "@playwright/mcp@latest"
            ]
          }
        }
      }
      ```
    </Accordion>

    <Accordion title="LM Studio">
      #### One-Click Install

      <a href="https://lmstudio.ai/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcGxheXdyaWdodC9tY3BAbGF0ZXN0Il19" target="_blank">
        Install in LM Studio
      </a>

      #### 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
    </Accordion>

    <Accordion title="opencode">
      Follow the [MCP Servers documentation](https://opencode.ai/docs/mcp-servers/).

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

      ```json theme={null}
      {
        "$schema": "https://opencode.ai/config.json",
        "mcp": {
          "playwright": {
            "type": "local",
            "command": [
              "npx",
              "@playwright/mcp@latest"
            ],
            "enabled": true
          }
        }
      }
      ```
    </Accordion>

    <Accordion title="Qodo Gen">
      1. Open the [Qodo Gen](https://docs.qodo.ai/qodo-documentation/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"
    </Accordion>

    <Accordion title="Warp">
      #### Settings UI

      1. Go to `Settings` → `AI` → `Manage MCP Servers` → `+ Add`
      2. Follow the [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) guide
      3. Use the standard configuration

      #### Slash Command

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

      ```json theme={null}
      {
        "mcpServers": {
          "playwright": {
            "command": "npx",
            "args": [
              "@playwright/mcp@latest"
            ]
          }
        }
      }
      ```
    </Accordion>
  </AccordionGroup>
</Accordion>

## 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:

```bash theme={null}
npx @playwright/mcp@latest --port 8931
```

Then configure your MCP client to connect via HTTP:

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}
```

### Docker Installation

<Note>
  The Docker implementation currently only supports headless Chromium.
</Note>

#### MCP Client Spawns Container

```json theme={null}
{
  "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:

```bash theme={null}
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

```bash theme={null}
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

<Tip>
  If tools aren't appearing, check your client's logs for connection errors or configuration issues.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Browser Not Installed">
    On first run, Playwright downloads browser binaries automatically. If you see errors about missing browsers:

    ```bash theme={null}
    npx playwright install
    ```

    Or use the `browser_install` tool from within your MCP client.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Create your first automation with Playwright MCP
  </Card>

  <Card title="Configuration" icon="gear" href="/guides/configuration">
    Learn about all configuration options and customization
  </Card>
</CardGroup>