snapmcp

snapmcp 2.3.11 turns agent-provided content into visual documentation artifacts: syntax-highlighted code, terminal sessions, browser pages, diffs, PDFs, GIFs, and captioned documents. It exposes exactly 13 MCP tools. The 12 capture/document tools return saved file paths rather than image bytes, while snapmcp-hint returns text guidance, keeping agent context small. Every tool also returns a structured payload with the saved path, format, and size.

Quick start

1. Install and initialize

Node.js 20 or newer is the primary runtime. Bun 1.2 or newer is optional.

npm install -g snapmcp
snapmcp init

npm and npx work without Bun. Package installation does not download a browser; snapmcp init explicitly installs Playwright Chromium for the reproducible default browser.

To try the server without a global install:

npx -y snapmcp init
npx -y snapmcp

2. Register it with an MCP client

Claude Code (~/.claude/claude.json):

{
  "mcpServers": {
    "snapmcp": {
      "command": "npx",
      "args": ["-y", "snapmcp"],
      "env": {
        "SNAPMCP_DIR": "./captures",
        "SNAPMCP_THEME": "nord"
      }
    }
  }
}

OpenCode (opencode.json or opencode.jsonc) keeps local servers under mcp.servers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "snapmcp": {
        "type": "local",
        "command": ["npx", "-y", "snapmcp"],
        "environment": {
          "SNAPMCP_DIR": "./captures",
          "SNAPMCP_FORMAT": "jpeg",
          "SNAPMCP_QUALITY": "95"
        }
      }
    }
  }
}

snapmcp init writes the current OpenCode V2 shape under mcp.servers for JSON and JSONC configuration files. JSONC comments, trailing commas, and unrelated settings are preserved. It also recognizes an existing deprecated mcp.snapmcp entry and leaves it unchanged to avoid creating a duplicate.

VS Code, Cline, and Roo-Cline use the same stdio command in their MCP server configuration.

3. Capture something

Ask the agent in natural language:

Capture a terminal screenshot of git log --oneline -5 and a syntax-highlighted image of src/index.ts.

The agent selects capture_terminal and capture_file. The capture_file call succeeds only when src/index.ts is covered by SNAPMCP_ALLOWED_PATHS; otherwise the agent can use capture_code with source text already in context. Generated files are saved under SNAPMCP_DIR, and the tool response contains their paths.

Related MCP server: aifmt

Why snapmcp versus Playwright MCP

Use Playwright MCP for browser interaction: clicking, filling forms, navigating, and reading accessibility trees. Use snapmcp when the deliverable is a visual artifact for a person to read.

The 13 tools

There is no additional capture tool. capture_batch, capture_sequence, capture_gif, and capture_document compose the same seven capture types: terminal, code, file, browser, Markdown, HTML, and diff.

Discovery for agents

Agents do not need to load the full documentation before choosing a tool:

• MCP tools/list is the canonical tool catalog.

• snapmcp-hint accepts a natural-language query, such as "website screenshot" or "pdf export".

• The MCP resource snapmcp://capabilities returns the machine-readable capability manifest.

• snapmcp capabilities --json prints the same compact manifest for shell and code-mode workflows.

• snapmcp search "<intent>" --json returns ranked matches for an intent.

• llms.txt and the server instructions provide concise selection guidance.

See the agent guide for selection rules, token-efficient behavior, and OpenCode/code-mode examples.

Common workflows

Automated documentation. Capture terminal output, highlighted source, and a visual diff, then embed the generated images in a guide or PR description.

Visual QA. Capture affected pages with capture_browser, produce several independent images with capture_batch, or record an ordered walkthrough with capture_sequence.

Technical tutorials. Use capture_sequence for ordered step images and capture_document when the final artifact should be a captioned Markdown, self-contained HTML, print-quality PDF, editable PowerPoint, or editable Word document.

Security boundaries

The defaults are designed for local use, not as a complete isolation boundary for hostile content.

• URL tools accept HTTP(S) only. With SNAPMCP_SSRF_PROTECTION=true by default, private and local IPv4/IPv6 literals, IPv4-mapped IPv6 addresses, localhost variants, and DNS names resolving to private addresses are blocked. Requests are revalidated as they occur.

• URL captures run through a local validating proxy that resolves and pins every target, including each redirect hop, so the address that was validated is the address that is connected to. Chromium is launched with a resolver rule that stops it from resolving target hostnames itself.

• File reads are deny-all until SNAPMCP_ALLOWED_PATHS is configured. Allowed files are resolved before the boundary check so symlinks cannot escape the allowlist.

• Every output is confined to SNAPMCP_DIR, including composite-tool outputs. Traversal and symlink escapes are rejected.

• Synthetic captures, including terminal, code, diff, Markdown, HTML, and generated document PDFs, render in an isolated browser context with JavaScript disabled, external network resources blocked, and a restrictive Content Security Policy. Markdown and HTML add content-specific handling: raw HTML in Markdown is escaped and raw HTML input is DOM-sanitized. These are defense-in-depth controls, not a guarantee of perfect sanitizer safety.

• Inputs are bounded: terminal 1,000 lines; code, Markdown, and HTML 200 KB each; diff 500 KB; file 5 MB by default; batch 10 items; sequence 60 steps; GIF 2 to 60 frames; document 30 captures with up to 25 MB per embedded image and 75 MB total.

• SNAPMCP_SSRF_PROTECTION=false disables SSRF checks. SNAPMCP_SECURITY_CHECKS=false disables the broader validation layer, including the file-read allowlist and additional byte/file-size checks. Output confinement and HTTP(S)-only URL validation remain in force. Do not disable either in shared or hostile environments.

Read SECURITY.md for the enforced controls and their limits.

Configuration

Terminal color detection is heuristic: it reads colors from common terminal configuration files when possible. It does not parse ANSI escape sequences.

Browser profile support is experimental and is never selected automatically. SNAPMCP_CHROME_PROFILE launches Chromium with a persistent user-data directory; URL captures run in that context, so cookies and session state can be sent to the target site. Synthetic captures remain isolated. Use a dedicated profile and treat it as sensitive.

CLI

snapmcp                         Start the MCP server on stdio
snapmcp init                    Install Chromium and configure the environment
snapmcp doctor                  Diagnose runtime, browser, paths, and configuration
snapmcp doctor --json           Machine-readable diagnostics
snapmcp test                    Generate verification captures
snapmcp capabilities --json     Print the capability manifest
snapmcp search "<intent>" --json
                                Search tools by intent

Docker (optional)

Docker is an optional packaging surface. The image includes Chromium, runs as a non-root user, and speaks MCP over stdio:

docker run -i --rm \
  -e SNAPMCP_DIR=/app/captures \
  -v /path/to/output:/app/captures \
  ghcr.io/reeinharddd/snapmcp

The mounted output directory must be writable by the container's non-root user.

Documentation

Development

git clone https://github.com/reeinharddd/snapmcp
cd snapmcp
bun install
bun run build
bun test

Node.js 20 or newer is the primary runtime. Bun is optional for package installation and local development.

License

MIT. See LICENSE.