SuperSurf

MCP-native browser automation. Any agent. Any model. Real browser. Undetectable.

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

Loading

SuperSurf is a free and open-source MCP server that gives any AI agent control of a real Chrome browser.
It works with any LLM that supports the Model Context Protocol — Claude, GPT, Gemini, open-source models, or your own.

Unlike tools that spin up headless browsers or inject CDP scripts, SuperSurf uses a Chrome extension to interact with pages through content scripts. Your agent operates in a real browser profile with your cookies, history, and localStorage intact — and page JavaScript can't detect it.

Every line of code — server and extension — is public. No obfuscated binaries, no telemetry, no data collection. Read it, audit it, fork it.

---

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?

vs. Puppeteer CDP over pipe — detectable via navigator.webdriver, CDP leak, and Runtime.evaluate VM artifacts. Fresh profile by default. Credentials pass through your script in plaintext. One connection per browser.

vs. Selenium WebDriver protocol — navigator.webdriver flag, predictable DOM mutation patterns. Fresh profile. Credentials in plaintext. Widely fingerprinted by commercial anti-bot systems.

SuperSurf Content scripts in an isolated world — invisible to page JS. Your real browser profile. Credentials resolved extension-side from env vars — agent never sees raw values. Built-in multi-agent multiplexing.

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  # Claude Code

Claude Desktop config

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

CLI flags can be appended to the args array:

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

From source (development)

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

---

Features

Undetectable DOM interaction	All page interaction runs through Chrome's content script context. No CDP fingerprints, no VM script artifacts, nothing for page JavaScript to observe.
Real browser profile	Your agent browses with your actual cookies, history, localStorage, and extensions. No sterile headless environment.
Secure credential handling	secure_fill injects passwords from environment variables directly in the extension. The agent sends an env var name, never the value.
30+ browser tools	Full coverage: navigation, interaction, screenshots, network monitoring, console access, form filling, CSS inspection, PDF export, performance metrics, file downloads.
Session multiplexing	Multiple MCP clients share one browser through a daemon process with tab ownership tracking and round-robin scheduling. The daemon is automatically spawned by the MCP server — no setup required.
Framework detection	Content script identifies 40+ frontend frameworks and libraries on any page.
CI-ready	Sideload the extension with --load-extension and a throwaway profile. No manual setup needed.
Domain whitelist	Optional navigation restriction using the Tranco top 100K list. Fetched once, cached locally, refreshed daily.
Zero extension deps	The Chrome extension uses browser APIs only. No bundled libraries, no supply chain surface.

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

Session Management

Tool	Description
connect	Connect to the browser daemon. Pass profile for an isolated Chromium instance.
disconnect	Disconnect from the browser daemon
status	Show connection state
experimental_features	Toggle experimental features
profile_create	Create an isolated Chromium profile (requires profiles experiment)
profile_list	List all managed profiles (requires profiles experiment)
profile_delete	Delete a managed profile (requires profiles experiment)

Navigation & Tabs

Tool	Description
browser_tabs	List, create, attach, or close tabs
browser_navigate	Go to URL, back, forward, reload
browser_window	Resize, close, minimize, maximize

Page Interaction

Tool	Description
browser_interact	Click, type, press keys, hover, scroll, wait, select, upload files
browser_fill_form	Set values on multiple form fields at once
browser_drag	Drag one element to another
browser_handle_dialog	Accept or dismiss alerts/confirms/prompts
secure_fill	Fill a field with a credential from an env var (agent never sees the value)

Content & Inspection

Tool	Description
browser_snapshot	Get the page's accessibility tree as structured DOM
browser_lookup	Find elements by visible text, returns CSS selectors
browser_extract_content	Pull page content as clean markdown
browser_get_element_styles	Inspect computed CSS like DevTools Styles panel
browser_evaluate	Run JavaScript in page context
browser_verify_text_visible	Assert text is visible on page
browser_verify_element_visible	Assert element is visible on page

Capture & Monitoring

Tool	Description
browser_take_screenshot	Capture viewport, full page, element, or region
browser_pdf_save	Export page as PDF
browser_console_messages	Read console output, filter by level/text/URL
browser_network_requests	Monitor/inspect/replay network traffic
browser_performance_metrics	Collect Web Vitals (FCP, LCP, CLS, TTFB)
browser_download	Download a file via the browser

Extensions & Storage

Tool	Description
browser_list_extensions	List installed Chrome extensions
browser_reload_extensions	Reload unpacked extensions
browser_storage	Inspect/modify localStorage & sessionStorage (requires storage_inspection experiment)
reload_mcp	Hot-reload the MCP server (debug mode only)

---

Experimental Features

Toggle via the experimental_features tool or the SUPERSURF_EXPERIMENTS environment variable:

SUPERSURF_EXPERIMENTS=page_diffing,smart_waiting,mouse_humanization,profiles

Experiment	Description
page_diffing	After interactions, returns only DOM changes instead of a full re-read. Includes a confidence score.
smart_waiting	Replaces fixed delays with adaptive DOM stability + network idle detection.
storage_inspection	Inspect and modify browser storage (localStorage, sessionStorage).
mouse_humanization	Human-like Bezier trajectories, overshoot correction, and idle micro-movements. Hand-tuned from the Balabit Mouse Dynamics dataset.
secure_eval	Two-layer code analysis for browser_evaluate. Server-side AST parsing + extension-side Proxy membrane that blocks dangerous API access before execution.
profiles	Isolated Chromium instances per agent session. Each profile gets its own cookies, storage, and browser state. Daemon spawns and manages Chromium processes, with matchmaker-based connection routing.

---

Server CLI Flags

Flag	Description
--debug	Verbose logging + hot reload (payloads truncated by default)
--debug=no_truncate	Full-verbosity debug — no payload truncation
--port <n>	WebSocket port (default: 5555)
--log-file <path>	Custom server log file path
--script-mode	JSON-RPC over stdio without MCP framing

Debug log locations

• 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
• 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.

---

100% Open Source — Apache-2.0 with Commons Clause. Free to use, modify, and redistribute, but not to sell.

Built by The Media Masons