graph LR
    A["AI Agent"] -->|stdio| B["MCP Server"]
    B -->|Unix socket| E["Daemon"]
    E -->|WebSocket| C["Chrome Extension"]
    C -->|Content Scripts| D["Browser"]

    style A fill:#8A2BE2,stroke:#6A1B9A,color:#fff
    style B fill:#339933,stroke:#1B5E20,color:#fff
    style E fill:#1B5E20,stroke:#0D3B14,color:#fff
    style C fill:#4285F4,stroke:#1565C0,color:#fff
    style D fill:#FF6F00,stroke:#E65100,color:#fff

Teach Your AI Agent SuperSurf 🦀

Send this to your agent:

Read https://liquidbuiltit.github.io/Supersurf/skill.md and follow the instructions to automate your browser

1. Send the prompt above to your AI agent
2. Your agent reads the skill guide and learns SuperSurf's tools
3. They connect and start automating your browser

Why SuperSurf?

Puppeteer and Selenium are great tools for scripted automation and testing. SuperSurf solves a different problem: giving an AI agent a browser that looks and behaves like a human's.

Why Extension-Based?

[!IMPORTANT]
CDP-injected scripts appear as VM instances in memory profiling. Content scripts run in an isolated world that page JavaScript cannot observe. SuperSurf never touches the page's JS context for DOM interaction.

Real browser profile. No synthetic launch flags, no blank profile. Your agent browses with the same cookies, history, and extensions as a human user.

Extension presence is a human signal. Anti-bot systems check for installed extensions as evidence of a real user. A browser with zero extensions is suspicious.

[!TIP]
SuperSurf is CI-compatible out of the box. Sideload without user interaction:

chrome --load-extension=./extension --user-data-dir=/tmp/supersurf-profile

Quick Start

1. Install the Chrome extension from the Web Store

2. Register with your MCP client

claude mcp add supersurf -- npx supersurf-mcp@latest mcp  # Claude Code

{
  "mcpServers": {
    "supersurf": {
      "command": "npx",
      "args": ["supersurf-mcp@latest", "mcp"]
    }
  }
}

CLI flags can be appended to the args array:

{
  "mcpServers": {
    "supersurf": {
      "command": "npx",
      "args": ["supersurf-mcp@latest", "mcp", "--debug", "--port", "5555"]
    }
  }
}

npm run mcp
# or manually:
claude mcp add supersurf -- node server/dist/bin/supersurf.js mcp

Packages

SuperSurf ships as two npm packages:

• supersurf-mcp — the MCP server. This is what you install and point your client at.
• supersurf-daemon — the coordinator daemon. It's a dependency of supersurf-mcp, spawned automatically; you never install or configure it directly.

Why two packages and not a single supersurf? They were meant to merge into one supersurf package in v3. That name is currently squatted on npm by a stale, abandoned 0.0.1 placeholder (dead site, untouched for ~10 months), so the merge is on hold pending an ownership dispute. Until that resolves, the two ship separately under the names we own.

Features

[!NOTE]
Credentials never reach the agent. secure_fill resolves env var values extension-side and types characters with randomized delays (40-120ms) to mimic human input. Your agent sends "GITHUB_PASSWORD", not the password itself.

Tools

Experimental Features

Configure via ~/.supersurf/config.json (changes require a daemon restart) or the SUPERSURF_EXPERIMENTS environment variable:

SUPERSURF_EXPERIMENTS=page_diffing,smart_waiting,mouse_humanization

Server CLI Flags

[!NOTE]
secure_eval — two-layer code analysis for browser_evaluate (server-side AST parsing + extension-side Proxy membrane that blocks dangerous API access before execution) — is on by default. Disable it with the --disable-secure-eval flag or SUPERSURF_DISABLE_SECURE_EVAL=1.

• Server log: ~/.supersurf/logs/server.log
• Session logs: ~/.supersurf/logs/sessions/supersurf-debug-{client_id}-{timestamp}.log

All WebSocket commands log params and responses. CDP passthrough unwraps to show inner methods. Base64 payloads (screenshots, PDFs) are auto-redacted in truncated mode.

Prerequisites

• Node.js >= 18
• Chrome or Chromium — on Ubuntu/Mint, must be a deb install, not a Snap. Snap Chromium's home interface denies access to hidden directories, breaking managed profiles under ~/.supersurf/. Fix on Mint: sudo snap remove chromium && sudo apt install chromium. Ubuntu has no first-party deb — use google-chrome-stable from Google's signed apt repo instead.
• An MCP client (Claude Code, Claude Desktop, etc.)
• macOS or Linux — Windows is not currently supported. Vote for Windows support if you'd like to see it.