convez.ai
MCP ServerAutomaçãoIntermediário
LiquidBuiltIt

SuperSurf MCP

LiquidBuiltIt/Supersurf

Automação de navegador real para agentes IA via extensão Chrome

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece controle de navegador Chrome real para agentes IA, via extensão do navegador. Funciona com qualquer LLM compatível com Model Context Protocol (Claude, GPT, Gemini, modelos open-source) e oferece 28 ferramentas de automação web sem detecção por JavaScript da página.

Instalação

$npx convez-ai LiquidBuiltIt/Supersurf

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v4.1.0
Issues abertas
1
Contribuidores
2

Casos de uso

  • Automação de tarefas web complexas por agentes IA
  • Scraping e coleta de dados com contexto real do navegador
  • Testes de aplicações web com interação natural do browser
  • Navegação e preenchimento de formulários em sites que requerem cookies/sessão

Veredito

SuperSurf é uma solução técnica robusta que resolve um problema real: automação invisível em navegadores reais sem detecção. A arquitetura via extensão (não CDP) é genuinamente diferenciada, com código totalmente aberto para auditoria. Ideal para construtores que precisam de automação web confiável em agentes IA.

README

A tradução para o português deste README ainda está na fila.

SuperSurf

MCP-native browser automation. Any agent. Any model. Real Chrome, via extension — not CDP.

npm version License Node.js TypeScript MCP Chrome Web Store Tools

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

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

Isolated-world DOM interactionAll page interaction runs through Chrome's content script context — an isolated world the page's own JavaScript can't read. No CDP fingerprints, no VM script artifacts. (Not tested against commercial anti-bot vendors.)
Real browser profileYour agent browses with your actual cookies, history, localStorage, and extensions. No sterile headless environment.
Secure credential handlingsecure_fill injects passwords from environment variables directly in the extension. The agent sends an env var name, never the value.
28 browser toolsFull coverage: navigation, interaction, screenshots, network monitoring, console access, form filling, CSS inspection, PDF export, performance metrics, file downloads.
Session multiplexingMultiple 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 detectionContent script identifies 40+ frontend frameworks and libraries on any page.
CI-readySideload the extension with --load-extension and a throwaway profile. No manual setup needed.
Domain whitelistOptional navigation restriction using the Tranco top 100K list. Fetched once, cached locally, refreshed daily.
Zero extension depsThe 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

ToolDescription
connectConnect to the browser daemon. Pass profile for an isolated Chromium instance.
disconnectDisconnect from the browser daemon
statusShow connection state
profile_createCreate an isolated Chromium profile
profile_listList all managed profiles
profile_deleteDelete a managed profile
ToolDescription
browser_tabsList, create, attach, or close tabs
browser_navigateGo to URL, back, forward, reload
browser_windowResize, close, minimize, maximize
ToolDescription
browser_interactClick, type, press keys, hover, scroll, wait, select, upload files
browser_fill_formSet values on multiple form fields at once
browser_dragDrag one element to another
browser_handle_dialogAccept or dismiss alerts/confirms/prompts
secure_fillFill a field with a credential from an env var (agent never sees the value)
ToolDescription
browser_snapshotGet the page's accessibility tree as structured DOM
browser_lookupFind elements by visible text, returns CSS selectors
browser_extract_contentPull page content as clean markdown
browser_get_element_stylesInspect computed CSS like DevTools Styles panel
browser_evaluateRun JavaScript in page context
browser_verify_text_visibleAssert text is visible on page
browser_verify_element_visibleAssert element is visible on page
ToolDescription
browser_take_screenshotCapture viewport, full page, element, or region
browser_pdf_saveExport page as PDF
browser_console_messagesRead console output, filter by level/text/URL
browser_network_requestsMonitor/inspect/replay network traffic
browser_performance_metricsCollect Web Vitals (FCP, LCP, CLS, TTFB)
browser_downloadDownload a file via the browser
ToolDescription
browser_list_extensionsList installed Chrome extensions
browser_storageInspect/modify localStorage & sessionStorage (requires storage_inspection experiment)
reload_mcpHot-reload the MCP server (debug mode only)

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
ExperimentDescription
page_diffingAfter interactions, returns only DOM changes instead of a full re-read. Includes a confidence score.
smart_waitingReplaces fixed delays with adaptive DOM stability + network idle detection.
storage_inspectionInspect and modify browser storage (localStorage, sessionStorage).
mouse_humanizationHuman-like Bezier trajectories, overshoot correction, and idle micro-movements. Hand-tuned from the Balabit Mouse Dynamics dataset.

Server CLI Flags

FlagDescription
--debugVerbose logging + hot reload (payloads truncated by default)
--debug=no_truncateFull-verbosity debug — no payload truncation
--port <n>WebSocket port (default: 5555)
--log-file <path>Custom server log file path
--script-modeJSON-RPC over stdio without MCP framing
--disable-secure-evalDisable the default-on secure_eval analysis (AST + Proxy membrane) for browser_evaluate

[!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.

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

Built by The Media Masons

Ver o original no GitHub

Bom para

Relacionados