snapmcp

Chuyển nội dung của agent thành tài liệu trực quan: đầu ra terminal, mã được tô sáng cú pháp, trang trình duyệt, Markdown, HTML, diff, PDF, GIF, chuỗi bước có thứ tự và tài liệu có chú thích ở định dạng Markdown, HTML, PDF, PowerPoint có thể chỉnh sửa và Word có thể chỉnh sửa.

Tài liệu

snapmcp

The visual documentation MCP server.
Terminal · Code · Browser · Markdown · HTML · Diff · PDF · GIF · Documents
For documentation workflows where structured snapshots are not the final artifact.

npm version npm downloads tests stars LobeHub MCP Glama score MIT


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.

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.

Use casesnapmcpPlaywright MCP
Terminal capture with detected terminal colorsYesNo
Code to syntax-highlighted imageYesNo
Git diff to visual red/green imageYesNo
URL to PDFYesNo
Captures to animated GIFYesNo
Browser page screenshotYesYes
Browser interaction and automationNoYes

The 13 tools

ToolUse it forResult
capture_terminalTerminal or CLI output, including $ and root # promptsPNG/JPEG path
capture_codeSource code with Shiki highlighting for 300+ bundled languages, 27 themes, and an optional inclusive line rangePNG/JPEG path
capture_browserFull-page or viewport screenshot of an HTTP(S) pagePNG/JPEG path
capture_fileAn allowlisted file, with extension-based language mapping and optional inclusive line rangePNG/JPEG path
capture_markdownGitHub-flavored Markdown rendered as a documentPNG/JPEG path
capture_htmlSanitized HTML/CSS rendered as a documentPNG/JPEG path
capture_diffUnified diff with additions and deletions highlightedPNG/JPEG path
capture_pdfThe complete HTTP(S) URL document printed with ChromiumPDF path
capture_batchUp to 10 independent captures in one callImage paths
capture_sequenceUp to 60 ordered step images, with an optional GIFImage paths and optional GIF path
capture_gifAn animation built from 2 to 60 capturesGIF path
capture_documentUp to 30 captioned captures embedded in a documentMarkdown/HTML/PDF/PPTX/DOCX path
snapmcp-hintTool discovery, setup, security, and token guidanceText

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

VariableDefaultDescription
SNAPMCP_DIR./capturesConfined output directory for every generated file
SNAPMCP_THEMEdetected terminal themeOne of 27 built-in Shiki themes
SNAPMCP_FORMATpngImage format: png or jpeg
SNAPMCP_QUALITY90JPEG quality from 1 to 100
SNAPMCP_PADDING32Content padding in pixels
SNAPMCP_SHADOWnonenone, soft, medium, or strong
SNAPMCP_WINDOW_CHROMEfalseShow a macOS-style title bar
SNAPMCP_BORDER_RADIUS0Window corner radius in pixels
SNAPMCP_BADGEfalseShow the snapmcp footer badge
SNAPMCP_LOG_FILEunsetOptional structured audit log path
SNAPMCP_CHROME_EXECUTABLEunsetExplicit system Chrome/Chromium executable; bundled Playwright Chromium is the default
SNAPMCP_CHROME_CHANNELunsetPlaywright Chrome channel such as stable, beta, dev, or canary
SNAPMCP_CHROME_PROFILEunsetExperimental persistent Chromium user-data directory: detected profile key/name or absolute path
SNAPMCP_ALLOWED_PATHSdeny-allComma- or semicolon-separated file-read allowlist
SNAPMCP_SSRF_PROTECTIONtrueBlock private and local URL targets
SNAPMCP_SECURITY_CHECKStrueEnable the broader validation layer

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

PageContents
Getting StartedInstallation, initialization, and client setup
Tools ReferenceAll 13 tools and the flat discriminated-union schemas
Agent GuideTool selection, discovery, token policy, and safety limits
ConfigurationEnvironment variables, browser behavior, and theme notes
CLI ReferenceSetup, diagnostics, discovery, and verification commands
GuidesTerminal, browser, GIF, and workflow examples
Security PolicyEnforced controls and known limits
ArchitectureCapability catalog, request flow, and security architecture
llms.txtConcise link-oriented guidance for agents

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.