Setting up Playwright MCP with Google Authentication

This guide explains how to configure Playwright MCP to work with websites that require Google authentication.

Prerequisites

• Node.js installed
• Playwright installed (npm install -D @playwright/test)
• Claude Desktop or Claude Code with MCP support

Step 1: Save Your Google Authentication

First, run the authentication script to save your Google login session:

# Install Playwright if not already installed
npm install -D @playwright/test

# Run the auth script
node scripts/save-google-auth.js

This will:

1. Open a Chrome browser
2. Navigate to your app's login page (update the URL in the script)
3. Let you complete the Google OAuth flow
4. Save the authentication state to ~/.playwright-google-auth.json

Step 2: Configure Claude to Use Saved Authentication

For Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add or update the Playwright MCP configuration:

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

For Claude Code

Run this command:

claude mcp add playwright npx @playwright/mcp@latest --storage-state ~/.playwright-google-auth.json

Option 2: Use a Persistent Browser Profile

Alternatively, you can use a persistent browser profile that maintains cookies between sessions:

Configure with User Data Directory

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-data-dir",
        "/Users/YOUR_USERNAME/.playwright-profile",
        "--browser",
        "chrome"
      ]
    }
  }
}

First time setup:

1. The browser will open with this profile
2. Manually log in to Google
3. The session will persist for future uses

Option 3: Use Configuration File (Advanced)

Create a configuration file at ~/.playwright-mcp-config.json:

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "channel": "chrome",
      "headless": false
    },
    "contextOptions": {
      "storageState": "/Users/YOUR_USERNAME/.playwright-google-auth.json"
    }
  },
  "capabilities": ["core", "tabs", "wait", "files"],
  "outputDir": "./playwright-output"
}

Then use it:

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

Testing Your Setup

Once configured, you can test by asking Claude to:

Can you navigate to [your authenticated URL] and take a screenshot?

Claude should be able to access the authenticated pages without needing to log in.

Refreshing Authentication

If your session expires:

1. Delete the storage state file: rm ~/.playwright-google-auth.json
2. Run the authentication script again
3. Restart Claude Desktop/Code

Security Notes

• The storage state file contains sensitive session data
• Keep it secure and don't share it
• Set appropriate file permissions: chmod 600 ~/.playwright-google-auth.json
• Consider using separate Google accounts for automation
• Rotate the authentication periodically

Troubleshooting

"Not authenticated" errors

• Ensure the storage state file exists and has correct permissions
• Try refreshing the authentication
• Check if the session has expired

Browser doesn't open

• Make sure Chrome is installed
• Try using --browser webkit or --browser firefox instead
• Check if --headless mode is preventing interaction

Session doesn't persist

• Use --user-data-dir instead of --storage-state
• Ensure the path is absolute, not relative
• Check file permissions on the profile directory