SuperSurf

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

What your agent can do with it

Check its own frontend work

The agent opens the tab on your dev server, clicks through the change it just made, and reads what you would read: console output, network requests, matched CSS rules with file and line, page timings and the accessibility tree. It fixes what it finds and checks again.

Do the chores that sit behind a login

Invoices in a vendor portal, forty records in a CRM, a report in an admin console. You are already signed in, so the agent is too: no second login, no 2FA prompt. Downloads go through your browser, so your cookies apply.

Save it as a playbook, rerun it without the model

Once the agent gets a flow right, save it as a playbook: a script you rerun from your terminal with no model in the loop, as often as you like. Every run is logged.

Quick Start

curl -fsSL https://liquidbuiltit.github.io/Supersurf/install.sh | sh

That installs the supersurf CLI to ~/.local/bin (no sudo), starts the daemon, and walks you through the one step it cannot do for you: installing the Chrome extension from the Web Store. Then point your client at it:

claude mcp add supersurf -- supersurf mcp   # Claude Code

Re-run the same command to upgrade. In CI, Docker, or anywhere without a terminal, it skips every prompt on its own — pass --yes to force that:

curl -fsSL https://liquidbuiltit.github.io/Supersurf/install.sh | sh -s -- --yes

Pass --client=claude to skip the manual claude mcp add step above — the installer runs it for you once the extension is connected:

curl -fsSL https://liquidbuiltit.github.io/Supersurf/install.sh | sh -s -- --client=claude

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

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

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

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

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 squatted on npm by an abandoned 0.0.1 placeholder, and npm declined to review the claim — its Trust & Safety team does not arbitrate squatting, and the trademark route it offered instead is not worth pursuing for a FOSS name. The merge is cancelled: SuperSurf ships as these two packages permanently. The supersurf CLI installed by the script above is a compiled binary from GitHub releases, not an npm package, so the squat does not affect it.

Safe to hand over

Also in the box

Tools

30 browser tools, grouped by job.

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.

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.

Support

SuperSurf is free and open-source. If it saves you time, you can support continued development: