Skip to main content
There are multiple ways to provide initial state to the browser context or page in Playwright MCP.

​
Storage State

Storage state allows you to load cookies and local storage into the browser context.

​
Using User Data Directory

Start with a user data directory to persist all browser data between sessions: 
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-data-dir",
        "/path/to/user-data"
      ]
    }
  }
}
This approach maintains full browser state including:
  • Cookies
  • Local storage
  • Session storage
  • IndexedDB
  • Cache
  • Extensions

​
Using Storage State File

Start with a storage state file to load cookies and local storage into an isolated browser context: 
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--storage-state",
        "path/to/storage.json"
      ]
    }
  }
}
Learn more about storage state in the Playwright documentation.

​
Page Initialization

​
Init Page Script

Use --init-page to point to a TypeScript file that will be evaluated on the Playwright page object. This allows you to run arbitrary code to set up the page. Example: Set geolocation and viewport
init-page.ts
export default async ({ page }) => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
  await page.setViewportSize({ width: 1280, height: 720 });
};
Configuration: 
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--init-page",
        "./init-page.ts"
      ]
    }
  }
}

​
Init Script

Use --init-script to point to a JavaScript file that will be added as an initialization script. The script will be evaluated in every page before any of the page’s scripts. This is useful for:
  • Overriding browser APIs
  • Setting up the environment
  • Injecting custom global variables
Example: Add custom flag
init-script.js
window.isPlaywrightMCP = true;
Configuration: 
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--init-script",
        "./init-script.js"
      ]
    }
  }
}

​
Multiple Init Scripts

You can specify multiple init scripts. They will be evaluated in the order specified: 
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--init-script",
        "./script1.js",
        "--init-script",
        "./script2.js"
      ]
    }
  }
}

​
Combined Approaches

You can combine multiple initialization methods: 
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--storage-state",
        "./auth.json",
        "--init-page",
        "./init-page.ts",
        "--init-script",
        "./init-script.js"
      ]
    }
  }
}