Skip to main content

Browser Profiles and Emulation

Emulation​

You can control which browser Playwright uses and how it simulates devices and environments. Below you'll find concise config examples you can paste into your configuration, along with guidance on when to use each option and a few troubleshooting tips.

Browser Selection​

Using a specific browser (example: msedge):

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

Example Prompt browser selection​

navigate to playwright.dev and tell me what browser you are using

If prompted to "Install the browser specified in the config", choose Allow. Playwright will download the required browser if missing, and the run will launch Microsoft Edge (msedge) instead of the default bundled Chromium.

Device Emulation​

Playwright comes with a registry of device parameters for selected desktop, tablet and mobile devices. It can be used to simulate browser behavior for a specific device such as user agent, screen size, viewport and if it has touch enabled. Emulating a mobile device (example: iPhone 13):

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

Example Prompt device emulation​

navigate to playwright.dev and take a screenshot and save it as iphone13.png

You should now have a full page screenshot emulating an iPhone 13 device.

Custom Viewport​

Playwright's default viewport is 1280x720. You can set a custom viewport size should you need to:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--viewport-size",
        "1600,720"
      ]
    }
  }
}

Example Prompt viewport size​

navigate to playwright.dev and tell me what viewport size is being used

Note that if you're using a persistent profile (the default), the viewport size will be saved and reused across sessions. If you want to return to the default viewport, you need to reset it explicitly.

Custom User Agent​

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-agent",
        "MyCustomUserAgent/1.0"
      ]
    }
  }
}

Ignore HTTPS Errors​

Only use this in development.

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

Browser Profiles and State​

By default, Playwright MCP uses persistent profiles. This means that user data, login states and cookies are preserved across sessions. For some usecases, this is the desired behavior as it allows the agent to stay logged in to websites and maintain session data.

In other usecases, this is not ideal because you want a clean slate every time the agent starts. There's a few ways to control this behavior.

Starting a Clean Session​

Isolated mode --isolated starts each session with a fresh, temporary browser profile. When the browser is closed or the MCP server restarts, all cookies, localStorage, and other storage for that session are discarded.

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

Providing Storage State​

To pre-populate a clean session with local storage and Cookies, you can use the --storage-state flag to load the state from a file. See docs on BrowserContext.storageState() for details on the file format.

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

Using a Custom User Data Directory​

To control where the browser stores its profile data, you can specify a path with the --user-data-dir flag.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-data-dir",
        "path/to/user/data"
      ]
    }
  }
}

Connecting to an Existing Browser Session​

You can connect to a running instance of Chrome or Edge using the --extension flag. This allows the AI assistant to interact with websites where you're already logged in, using your existing cookies, sessions, and browser state. This requires the "Playwright MCP Bridge" browser extension to be installed.

Extension Installation​

  1. Download the Extension: Download the latest chrome-extension.zip from the Playwright MCP GitHub releases page.
  2. Unzip the file.
  3. Load the Extension:
    • Open your Chrome/Edge browser and navigate to chrome://extensions/.
    • Enable "Developer mode" using the toggle in the top-right corner.
    • Click "Load unpacked" and select the unzipped extension directory.

Once the extension is installed, you can use the --extension flag in your configuration.

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

Connecting to a CDP Endpoint​

For advanced use cases, you can connect to a running browser's Chrome DevTools Protocol (CDP) endpoint using the --cdp-endpoint flag.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--cdp-endpoint",
        "ws://127.0.0.1:9222/devtools/browser/..."
      ]
    }
  }
}

Using a Configuration File​

Big configurations can be hard to manage inline, so we allow you to manage them in a separate file using the --config flag.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--config",
        "path/to/your/config.json"
      ]
    }
  }
}

config.json example:

{
  "browser": {
    "browserName": "edge",
    "isolated": true,
    "launchOptions": { "headless": true },
    "contextOptions": { "viewport": { "width": 1280, "height": 720 } }
  },
  "server": { "host": "0.0.0.0", "port": 8931 },
  "capabilities": ["verify", "pdf"],
  "network": { "allowedOrigins": ["https://example.com"], "blockedOrigins": ["https://tracker.example"] },
  "imageResponses": "omit",
  "outputDir": "./mcp-output"
}

Check the README for details on the configuration file format and options.