# snapsurf [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/zumerlab/snapsurf  
**GitHub Stars:** 0  
**npm Downloads (last month):** 374  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/snapsurf

## Description
Web navigation and verification for AI agents: page digest, typed diff per action, assertions.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "snapsurf": {
    "command": "npx",
    "args": ["-y","-p","@zumer/snapsurf@latest","snapsurf-mcp"]
  }
}
```

## Documentation

## What snapsurf MCP server does

snapsurf MCP server provides browser navigation and verification for AI agents through a local Chromium session. Rather than returning only a snapshot of the current page, it records the transition caused by an action and describes observable differences in content, state, layout, and clickability. A result can also explicitly report that no observable change occurred or that evidence is unavailable.

The server fits the Browser Automation category and is useful for workflows where an agent must confirm that a click, input, or other browser action produced a specific result. It can run as an MCP server or through the accompanying command-line interface. The observation code can also be used as an in-page library built on SnapDOM.

## How it works

A typical agent loop opens a page with `browser_open`, searches for controls with `browser_find`, performs an operation with `browser_act`, and then calls `browser_verify`. Verification returns structured content describing the latest transition and may include a `diffId`. That identifier can be supplied to `browser_assert` to check the exact retained evidence without observing the page again or moving the live baseline forward.

Assertions can test whether something changed, require specified additions such as a dialog, or reject specified removals. A separate live assertion can check current page state. Failed checks report `pass: false` and return an MCP error. Element identifiers belong to an observation and can expire after a new observation, so agents should locate controls again when needed.

## Setup and configuration

The snapsurf MCP server requires Node.js 22 or newer. A standard stdio configuration can run it through `npx`:

```json
{
  "command": "npx",
  "args": ["-y", "-p", "@zumer/snapsurf@latest", "snapsurf-mcp"]
}
```

Chromium for Playwright is installed automatically on first startup. On Linux systems missing required libraries, install Chromium and its dependencies with `npx playwright install --with-deps chromium`. To avoid downloading at startup or to pin a package version, install `@zumer/snapsurf` locally and point the client at `mcp/server.mjs`.

The package also supports a CLI daemon. Start it with `npx -y @zumer/snapsurf serve`, then use commands such as `open`, `assert`, and `stop` from another terminal. The README refers to `SNAPSURF_*` settings for the port, token file, and log directory, but does not list the individual variable names.

## Tools and capabilities

- `browser_open` opens a page in the managed Chromium session.
- `browser_find` locates controls for later actions.
- `browser_act` performs browser actions against a located target.
- `browser_verify` produces a semantic digest and typed diff for the latest transition.
- `browser_assert` checks retained evidence or evaluates current state.

Reports distinguish content, state, layout, and clickability changes. They can include structured content for programmatic handling, including assertion results and retained diff identifiers.

## Limitations and notes

The snapsurf MCP server uses its own cookies and storage, so it cannot reuse signed-in sessions from a user's normal browser. An `authState` value of `unknown` is not proof that authentication succeeded. Canvas content, iframe documents, and closed shadow roots may not be fully represented in semantic reports; a scoped screenshot may be needed in those cases.

A `changed: false` result means that no observable change was detected, not that the requested task succeeded. Page text is treated as untrusted data. Semantic reports support redaction, but screenshots from the CLI or MCP server may still contain sensitive content. Version 0.1.3 is experimental.

_Full upstream README: https://allmcps.com/mcp/snapsurf/readme_