Supersurf MCP

What supersurf-mcp does

supersurf-mcp gives an MCP-compatible agent control of Chrome through an extension. It can operate tabs, navigate pages, interact with visible controls, submit forms, upload files, handle browser dialogs, and inspect page state. The browser can be the Chrome instance already used by the operator, allowing workflows to use existing tabs, sessions, cookies, and logins.

The server also supports managed Chromium profiles for separate accounts or isolated sessions. Agents can create, list, and delete these profiles, then connect to a profile when starting a session. Session cleanup closes tabs created by the agent and releases tabs it attached to.

How it works

The MCP server runs locally over stdio. It starts or uses the SuperSurf daemon, which communicates with the Chrome extension over a Unix socket and WebSocket connection. The extension uses content scripts to act on the browser.

An agent begins with connect, using a client_id and optionally a managed profile. status reports whether the connection is passive, active, or connected. In opt-in multi-agent mode, sessions use username instead of client_id. disconnect ends the session and performs the associated tab cleanup.

Page inspection includes an accessibility-tree snapshot, visible-text lookup, cleaned Markdown extraction, computed CSS inspection, JavaScript evaluation, and assertions for visible text or elements. Browser diagnostics include console messages, network request inspection and replay, performance timings, storage access, and installed-extension listing. Agents can also capture screenshots, export pages as PDFs, and download files through the browser.

Setup and configuration

The installer is available through the project’s shell script:

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

It installs the supersurf CLI under ~/.local/bin, starts the daemon, and guides Chrome extension installation. The MCP server can also be run directly through npm:

npx supersurf-mcp@latest

For Claude Code, add it with:

claude mcp add supersurf -- npx supersurf-mcp@latest

Claude Desktop can launch it with a configuration whose command is npx and whose argument is supersurf-mcp@latest. The server accepts options such as --debug and --port. Node.js 18 or newer is required.

The extension normally comes from the Chrome Web Store. Managed profiles can launch a separate Chromium instance with the extension already sideloaded; a manual unpacked extension or a CI --load-extension setup is also supported.

Tools and capabilities

• Manage connections and isolated profiles.
• List, create, attach, and close tabs.
• Navigate, resize, minimize, maximize, and close browser windows.
• Click, type, select, scroll, hover, wait, upload, drag, and fill multiple fields.
• Fill credentials from environment variables without exposing their values to the agent.
• Inspect accessibility structure, content, styles, JavaScript results, storage, console output, requests, and performance metrics.
• Capture viewport, full-page, element, or region screenshots; save PDFs and download files.
• Accept or dismiss alerts, confirms, and prompts.

Limitations and notes

The server depends on the Chrome extension and local daemon connection. The reload_mcp tool is available only in debug mode. Self-healing selectors and smart waiting are experimental. An optional domain allowlist can restrict navigation, and page scripts are checked before execution with network calls, storage access, and navigation blocked by default. Credential filling requires the relevant value to be available through an environment variable.