MCP 服务器

snapmcp

Visual documentation MCP server with 13 tools to capture terminal screenshots, syntax-highlighted code, visual diffs, PDFs, GIFs, and more for documentation workflows.

README

The visual documentation MCP server. Terminal · Code · Browser · Markdown · Diff · HTML · PDF · GIF For documentation workflows — when structured snapshots aren't enough.

Real terminal colors, Shiki-highlighted code, visual diffs, PDFs and GIFs — one MCP server, 13 tools, zero heavy dependencies. SSRF protection on by default. Built for agents that write documentation, not just drive browsers.

Quick Start

Three steps, under two minutes:

1. Install

npm install -g snapmcp
# or run without installing: npx -y snapmcp

2. Add to Claude Code (~/.claude/claude.json)

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

3. Capture

Ask your agent in natural language:

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

The agent calls capture_terminal and capture_file — images land in ./captures/ with your real terminal theme and the chosen syntax theme applied.

<details> <summary>Other clients: OpenCode, VS Code / Cline, Docker</summary>

OpenCode (opencode.json):

{
  "mcpServers": {
    "snapmcp": {
      "command": "npx",
      "args": ["-y", "snapmcp"],
      "env": {
        "SNAPMCP_DIR": "./captures",
        "SNAPMCP_FORMAT": "jpeg",
        "SNAPMCP_QUALITY": "95"
      }
    }
  }
}

VS Code / Cline / Roo-Cline (settings.json → cline.mcpServers):

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

Docker:

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

</details>

What it looks like

Real screenshots generated by snapmcp:

Capture	Preview
Terminal (real detected colors)	<img src="docs/assets/test-terminal.png" alt="terminal capture" width="300"/>
Code (Shiki syntax)	<img src="docs/assets/test-code.png" alt="code capture" width="300"/>
Diff (green/red)	<img src="docs/assets/diff-example.png" alt="diff capture" width="300"/>
Markdown render	<img src="docs/assets/markdown-preview.png" alt="markdown render" width="300"/>

Why snapmcp vs Playwright MCP

Different tools for different jobs. Playwright MCP drives a browser through token-efficient accessibility snapshots; snapmcp renders pixel-faithful images for humans to read. If your agent needs to click, use Playwright. If it needs to show, use snapmcp.

Use case	snapmcp	Playwright MCP
Terminal capture with real colors	✅ auto-detects Kitty, Gnome, Alacritty, WezTerm themes	❌ no terminal support
Code → syntax-highlighted image	✅ Shiki, 50+ languages, 27 themes	❌ not its purpose
Git diff → visual red/green image	✅ `capture_diff`	❌
URL → PDF document	✅ `capture_pdf`	❌
Animated GIF from captures	✅ `capture_gif` (zero-dep gifenc)	❌
Markdown → styled document	✅ `capture_markdown`, `capture_to_document`	❌
Browser page screenshot	✅ `capture_browser` (full-page or viewport)	✅
Browser automation (click, fill, navigate)	❌ screenshots only	✅ accessibility-tree driven, token-efficient — the right tool for this

Most documentation pipelines pair them: Playwright MCP to interact, snapmcp to document.

Tools

Tool	Description
`capture_terminal`	Terminal output with syntax-colored prompts (auto-detects real terminal theme)
`capture_code`	Syntax-highlighted code via Shiki (50+ languages, 27 themes)
`capture_browser`	Full-page or viewport screenshots (uses system Chrome profile when available)
`capture_file`	File → auto-detected language → highlighted screenshot
`capture_markdown`	Rendered markdown as a styled document
`capture_html`	Arbitrary HTML snippet rendered as image
`capture_diff`	Git diffs with green additions / red deletions
`capture_pdf`	URL → PDF document
`capture_batch`	Batch capture multiple items in one call
`capture_gif`	Animated GIF from multiple screenshots
`capture_sequence`	Side-by-side animated sequence
`capture_to_document`	Multi-section markdown document render
`snapmcp-hint`	Server capability hints for MCP clients

Use cases

Automated documentation — an agent writes a setup guide and embeds real captures: the terminal output of the install command (with your actual theme), the config file syntax-highlighted, the diff of the migration. One prompt, three capture_* calls, images saved next to the markdown.

Visual QA — after a UI change, the agent captures the affected pages with capture_browser, batches before/after with capture_batch, and assembles an animated comparison with capture_gif for the PR description.

Terminal guides — CLI tutorials where the screenshots must match what readers will see: capture_terminal reproduces the real prompt colors instead of a generic dark rectangle.

Security

SSRF protection is on by default — no opt-in required.

Feature	Description
SSRF Protection	On by default (disable with `SNAPMCP_SSRF_PROTECTION=false`). Blocks IP literals (v4 + v6), localhost variants, and DNS names that resolve to private ranges (`127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`, `fe80::/10`, etc.); every page request (redirects included) is re-checked
File Allowlist	`SNAPMCP_ALLOWED_PATHS` defaults to deny-all when unset; only explicitly allowed paths can be captured
Path Traversal	Prevents `../` escapes, symlink traversal (via realpath), and null byte injection
Input Limits	Terminal 1000 lines; code/markdown/HTML 200KB; diff 500KB; file reads 5MB; max GIF frames 60; max GIF canvas 8192×8192
Audit Log	Optional structured JSON log file with timestamped events
Chromium Sandbox	Sandbox availability checked at startup

Configuration

Environment variables for the MCP server:

Variable	Default	Description
`SNAPMCP_DIR`	`./captures`	Output directory for captures
`SNAPMCP_THEME`	auto-detected	Syntax theme (27 built-in themes + auto-detected terminal)
`SNAPMCP_FORMAT`	`png`	Output format (`png`, `jpeg`)
`SNAPMCP_QUALITY`	`90`	JPEG quality (1-100)
`SNAPMCP_PADDING`	`32`	Content padding in pixels
`SNAPMCP_SHADOW`	`none`	Drop shadow (`none`, `soft`, `medium`, `strong`; aliases `sm`/`md`/`lg`)
`SNAPMCP_WINDOW_CHROME`	`false`	macOS-style title bar frame
`SNAPMCP_BORDER_RADIUS`	`0`	Window corner radius
`SNAPMCP_BADGE`	`false`	Footer badge
`SNAPMCP_LOG_FILE`	—	Audit log file path
`SNAPMCP_CHROME_EXECUTABLE`	—	Path to Chrome/Chromium binary
`SNAPMCP_CHROME_CHANNEL`	—	Chrome channel (`stable`, `beta`, `dev`, `canary`)
`SNAPMCP_CHROME_PROFILE`	—	Chrome profile directory name
`SNAPMCP_ALLOWED_PATHS`	(deny-all)	Comma- or semicolon-separated allowed file paths for `capture_file`

27 built-in Shiki themes: dracula, one-dark-pro, nord, tokyo-night, catppuccin-mocha, catppuccin-latte, ayu-dark, ayu-light, vitesse-dark, vitesse-light, min-dark, min-light, poimandres, rose-pine, rose-pine-moon, rose-pine-dawn, slack-dark, slack-ochin, snazzy-light, github-dark-dimmed, github-light, one-light, solarized-light, solarized-dark, material-theme, material-theme-lighter, material-theme-ocean

CLI

SnapMCP ships with a full CLI beyond the MCP server:

snapmcp        — Start the MCP server
snapmcp init   — Interactive setup wizard (detects Chrome, terminal theme, output dir)
snapmcp doctor — Health check: 7 checks across Node, Chromium, paths, env
snapmcp test   — Generate test captures (terminal + code) to verify the setup

Documentation

Page	Contents
Getting Started	Installation, quick start, MCP client setup
Tools Reference	All 13 tools with parameters and examples
Configuration	All SNAPMCP_* env vars, themes, defaults
CLI Reference	Init, doctor, test commands
Guides	Terminal capture, browser capture, GIF animation
ARCHITECTURE.md	Module map, data flow, security architecture
CONTRIBUTING.md	Dev workflow, testing guidelines, PR checklist

Development

git clone https://github.com/reeinharddd/snapmcp
cd snapmcp
bun install
bun run build    # tsc → dist/
bun test         # 317 tests

Requirements: Node.js ≥ 20 or Bun ≥ 1.2. CI runs on ubuntu / macOS / windows via GitHub Actions.

License

MIT — see LICENSE.