# Playwright MCP Supercharged

A supercharged fork of [@playwright/mcp](https://github.com/microsoft/playwright-mcp) that adds **multi-session support** and **Chrome cookie import** — run multiple isolated browser contexts simultaneously, and log into any site your Chrome is already logged into.

## Why?

The upstream Playwright MCP server supports only a single browser context and has no way to import auth sessions. This fork adds:

- Run **multiple browser sessions in parallel** (e.g., one for Shopify admin, one for your app)
- **Import cookies from Chrome** — one tool call, no passwords, access any site you're logged into
- **Target any session** by passing `sessionId` to any tool
- **Switch between sessions** without closing/reopening browsers
- Each session has **independent tabs, cookies, storage, and state**

## Getting Started

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["playwright-mcp-supercharged"]
    }
  }
}
```

Or run from this repo:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": ["/path/to/playwright-mcp-supercharged/packages/playwright-mcp/cli.js"]
    }
  }
}
```

## Session Management Tools

| Tool | Description |
|------|-------------|
| `session_create` | Create a new isolated browser session |
| `session_list` | List all active sessions and show which is active |
| `session_switch` | Change the active (default) session |
| `session_close` | Close a session and dispose its browser |

## Using Sessions

Every existing Playwright tool now accepts an optional `sessionId` parameter:

```
# Create two sessions
session_create({ sessionId: "shopify" })
session_create({ sessionId: "admin" })

# Navigate each independently
browser_navigate({ url: "https://shopify.com/admin", sessionId: "shopify" })
browser_navigate({ url: "https://admin.example.com", sessionId: "admin" })

# Take snapshots from specific sessions
browser_snapshot({ sessionId: "shopify" })
browser_snapshot({ sessionId: "admin" })

# Switch active session (used when sessionId is omitted)
session_switch({ sessionId: "shopify" })
browser_snapshot()  # → uses "shopify" session

# Close when done
session_close({ sessionId: "admin" })
```

### Auto-creation

If you call a tool with a `sessionId` that doesn't exist yet, the session is created automatically. You don't need to call `session_create` first.

If you don't pass `sessionId` at all, a `"default"` session is used.

## Cookie Import from Chrome

Access sites you're already logged into in Chrome. The MCP decrypts cookies directly from Chrome's encrypted database on macOS.

```
# Import cookies for a domain into a session
session_import_cookies({ domain: "shopify.com", sessionId: "shopify" })

# Now navigate — you're logged in
browser_navigate({ url: "https://admin.shopify.com", sessionId: "shopify" })
```

Works for any site: Shopify, GitHub, AWS, Google, etc. No passwords needed — it reads your existing Chrome sessions.

**For captcha-protected sites** (Shopify, Google), run without `--headless` so you get a visible browser window. After cookie import, you may need to click through a captcha once in the visible window, then the AI takes over.

**Three ways to authenticate a session:**

| Method | Use case |
|--------|----------|
| `session_import_cookies({ domain })` | Best for most cases. Decrypts from Chrome. macOS only. |
| `session_create({ cookiesFile })` | Pre-exported cookies in JSON format. Cross-platform. |
| `session_create({ cdpEndpoint })` | Connect to running Chrome via DevTools Protocol. |

## CLI Options

```bash
playwright-mcp-supercharged [options]

Options:
  --browser <browser>         Browser: chromium, firefox, webkit (default: chromium)
  --headless                  Run in headless mode
  --vision                    Enable vision/screenshot capabilities
  --caps <capabilities>       Comma-separated capabilities
  --image-responses <mode>    allow or omit (default: allow)
```

## How It Works

```
┌─────────────────────────────────────────────────┐
│           MCP Server (this fork)                │
│                                                 │
│  ┌──────────────────────────────────────────┐   │
│  │       MultiSessionBackend                │   │
│  │                                          │   │
│  │  sessions: Map<sessionId, Backend>       │   │
│  │                                          │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐   │   │
│  │  │ shopify  │ │  admin  │ │ default │   │   │
│  │  │ Browser  │ │ Browser │ │ Browser │   │   │
│  │  │ Context  │ │ Context │ │ Context │   │   │
│  │  │ Tabs...  │ │ Tabs... │ │ Tabs... │   │   │
│  │  └─────────┘ └─────────┘ └─────────┘   │   │
│  └──────────────────────────────────────────┘   │
│                                                 │
│  Tool call: browser_navigate(url, sessionId)    │
│       → routes to correct Backend               │
└─────────────────────────────────────────────────┘
```

Each session gets its own `playwright.Browser` instance with an isolated `BrowserContext`. All upstream Playwright MCP tools work unchanged — we just add the `sessionId` routing layer.

## License

Apache-2.0 (same as upstream)

## Credits

Based on [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp).