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

# Initial State

> Set up initial browser and page state for Playwright MCP sessions

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:

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

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--storage-state",
        "path/to/storage.json"
      ]
    }
  }
}
```

Learn more about storage state in the [Playwright documentation](https://playwright.dev/docs/auth).

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

```typescript init-page.ts theme={null}
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:**

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

```javascript init-script.js theme={null}
window.isPlaywrightMCP = true;
```

**Configuration:**

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

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--init-script",
        "./script1.js",
        "--init-script",
        "./script2.js"
      ]
    }
  }
}
```

## Combined Approaches

You can combine multiple initialization methods:

<CodeGroup>
  ```json Command-line theme={null}
  {
    "mcpServers": {
      "playwright": {
        "command": "npx",
        "args": [
          "@playwright/mcp@latest",
          "--storage-state",
          "./auth.json",
          "--init-page",
          "./init-page.ts",
          "--init-script",
          "./init-script.js"
        ]
      }
    }
  }
  ```

  ```json Configuration File theme={null}
  {
    "browser": {
      "contextOptions": {
        "storageState": "./auth.json"
      },
      "initPage": ["./init-page.ts"],
      "initScript": ["./init-script.js"]
    }
  }
  ```
</CodeGroup>