Skip to main content

Profile & State

Playwright MCP manages browser state through profiles. By default, login state and cookies persist between sessions automatically.

Profile modes​

Persistent (default)​

Login state, cookies, and local storage are preserved between sessions. The profile directory name includes the browser channel and a hash of the client's workspace directory, so different projects get separate profiles automatically.

PlatformDefault location
macOS~/Library/Caches/ms-playwright-mcp/mcp-{channel}-{workspace-hash}
Linux~/.cache/ms-playwright-mcp/mcp-{channel}-{workspace-hash}
Windows%LOCALAPPDATA%\ms-playwright-mcp\mcp-{channel}-{workspace-hash}

Override the profile location:

["@playwright/mcp@latest", "--user-data-dir=/path/to/profile"]

A profile can only be used by one browser at a time. If it is already locked, the server fails to start.

note

The Playwright CLI defaults to in-memory state instead (cookies persist between commands but are lost when the browser closes). Use --persistent there to enable disk persistence. See Sessions & Dashboard for CLI-specific session management.

Isolated​

Each session starts fresh with no saved state, and nothing is written to disk. Pass --isolated to enable:

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

--isolated cannot be combined with --user-data-dir. Load initial state into an isolated session with --storage-state:

["@playwright/mcp@latest", "--isolated", "--storage-state=./auth-state.json"]

Browser extension​

Connect to your existing browser tabs instead of launching a new browser. See Browser Extension.

Saving and restoring state​

Save authenticated state for reuse across sessions with the storage capability:

// Login, then save
→ browser_storage_state { filename: "auth-state.json" }
  - [Storage state](auth-state.json)

// Later: restore
→ browser_set_storage_state { filename: "auth-state.json" }

Or load state automatically on server startup with --storage-state. See Storage & Authentication for the full workflow.