# supersurf-mcp [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/liquidbuiltit/Supersurf  
**GitHub Stars:** 8  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/supersurf-mcp

## Description
Open-source MCP server for browser automation — gives AI agents control of a real Chrome browser via extension

## Tools
Capabilities this server exposes over MCP:

- **connect** — Connect and start a session named by `client_id`. Pass `profile` for an isolated Chromium instance. (Opt-in multi-agent mode, `agents.multi_agent`, takes `username` instead.)
- **disconnect** — End your session: closes the tabs you created, releases tabs you attached to
- **status** — Show current connection state: passive, active, or connected
- **profile_create** — Create an isolated Chromium profile
- **profile_list** — List all managed profiles
- **profile_delete** — Delete a managed profile
- **browser_tabs** — List, create, attach, or close tabs
- **browser_navigate** — Go to URL, back, forward, reload
- **browser_window** — Resize, close, minimize, maximize
- **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)
- **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
- **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 page timings (TTFB, FCP, DOMContentLoaded, Load)
- **browser_download** — Download a file via the browser
- **browser_list_extensions** — List installed Chrome extensions
- **browser_storage** — Inspect/modify localStorage & sessionStorage
- **reload_mcp** — Hot-reload the MCP server *(debug mode only)*

## Claude Desktop Quick Installation
No generated config for this server: it installs through its own setup steps.

The project's own setup steps (from https://github.com/liquidbuiltit/Supersurf), copied verbatim. Run them in order; they are not an mcpServers config.

1. Install:

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

2. Add to Claude Code:

```sh
claude mcp add supersurf -- supersurf mcp   # Claude Code
```

3. Install:

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

4. Install:

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

5. Add to Claude Code:

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

6. Install:

```sh
npm ci
```

## Documentation

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

```bash
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:

```bash
npx supersurf-mcp@latest
```

For Claude Code, add it with:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/supersurf-mcp/readme_