snapmcp

All-in-one MCP server for visual captures.
Terminal · Code · Browser · Markdown · Diff · HTML · PDF · GIF
One server. 13 tools. Real fidelity. Zero juggling.

Generate screenshots of terminals, code, web pages, markdown, diffs, PDFs, and GIF animations — all through a single MCP server. No more juggling 4 different MCP servers for your visual capture needs.

Features

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

Documentation

Full reference documentation at docs/ — organized like a site with hyperlinks between pages:

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

v2.2 Highlights

• Real Terminal Colors — detects Kitty, Gnome Terminal, Alacritty, WezTerm, Xfce4, and LXTerminal configs for authentic terminal captures
• Real Browser Profile — finds system Chrome/Edge/Brave installations and uses your real user data directory
• In-Project Captures — saves to ./captures in your current project, not an isolated directory
• SSRF Protection — opt-in URL protection that blocks private/internal IP ranges (enable via SNAPMCP_SSRF_PROTECTION=true)
• Audit Logging — optional structured audit log file with timestamped events
• Centralized Brand — consistent teal/blue ANSI output across all CLI commands
• Zero-Dep GIF — migrated from gifencoder to gifenc + fast-png (7 fewer security vulnerabilities)
• Interactive Setup — guided wizard with dependency detection and configuration

Quick Start

# Install globally
npm install -g snapmcp

# Start the server
snapmcp

Or run a quick health check:

# Run the interactive setup wizard
snapmcp init

# Check system readiness
snapmcp doctor

# Generate test captures
snapmcp test

Installation Guides

Claude Code

Add to your ~/.claude/claude.json:

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

OpenCode

Add to your opencode.json:

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

VS Code / Cline / Roo-Cline

Add to VS Code settings (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

CLI Commands

SnapMCP ships with a full CLI beyond the MCP server:

snapmcp        — Start the MCP server
snapmcp init   — Interactive setup wizard
snapmcp doctor — Health check for all dependencies
snapmcp test   — Generate test captures (terminal + browser)
snapmcp --help — Show available tools and version

snapmcp init

Interactive wizard that:

• Detects system state (Chrome, Playwright, output directory, theme)
• Guides you through configuration choices
• Installs Chromium if missing
• Prints a ready-to-use MCP config snippet

snapmcp doctor

Runs 7 checks:

• Node.js version ≥ 18
• Playwright Chromium installed
• Output directory writable
• SnapMCP version
• Chrome/Chromium detected
• System terminal theme detected
• Environment variables valid

snapmcp test

Generates sample captures to verify everything works:

• captures/test-terminal.png — terminal screenshot
• captures/test-code.png — code screenshot

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; invalid values fall back to none)
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

Real Fidelity

SnapMCP detects your real environment for authentic captures.

Terminal auto-detection (in priority order):

Source	Detection method
Kitty	kitty.conf (foreground, background, tab_bar_style)
Gnome Terminal	dconf /org/gnome/terminal/legacy/profiles:/
Alacritty	alacritty.toml / alacritty.yml (colors.*)
WezTerm	wezterm.lua (background detection)
Xfce4 Terminal	xfce4/terminal/terminalrc
LXTerminal	lxterminal.conf
COLORFGBG	Environment variable fallback
OS Theme	gsettings dark mode detection

Browser auto-detection (in priority order):

• SNAPMCP_CHROME_EXECUTABLE env var
• System Chrome paths (Linux: google-chrome, chromium-browser; macOS: /Applications/Google Chrome.app; Windows: %LOCALAPPDATA%\Google\Chrome)
• which / where PATH lookup
• Edge / Brave / Chromium fallbacks
• Bundled Playwright Chromium as final fallback

Security

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

Themes

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

Example Output

captures/
├── test-terminal.png   # Terminal output with real detected colors
├── test-code.png       # Syntax-highlighted code
├── page.png            # Full-page browser screenshot
└── output.pdf          # URL converted to PDF

Real screenshots generated by snapmcp:

Capture	Preview
Terminal
Code
Doctor
Init
Diff
Config

Architecture

src/
├── index.ts        — MCP server, 13 tool registrations, CLI entry
├── renderer.ts     — Capture engine + SSRF route guard (terminal, code, browser, PDF)
├── config.ts       — Config loader, defaults, 27 themes
├── cli.ts          — CLI commands (init, doctor, test)
├── security.ts     — SSRF denylist (incl. DNS resolve), path traversal, input limits
├── logger.ts       — Audit logging (AuditEvent, log file)
├── brand.ts        — Centralized brand tokens (colors, ANSI, logo)
├── terminal.ts     — Real terminal detection (Kitty/Gnome/Alacritty/WezTerm)
├── browser.ts      — System Chrome profile detection (8-step fallback)
├── setup-shared.ts — Shared bootstrap for interactive setup
├── document.ts     — Document render engine (brand-colored)
├── gif.ts          — GIF animation (gifenc + fast-png, zero deps)
├── tools/          — One file per MCP tool (13 registrations)
└── highlighter.ts  — Shiki wrapper

Development

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

Docs

Full reference documentation in docs/: getting started, tools reference, configuration, CLI, and guides.

Project Documentation

• ARCHITECTURE.md — Module map, data flow, key design decisions, security architecture, cross-platform support, and full MCP protocol reference. Required reading for anyone modifying the codebase.
• CONTRIBUTING.md — Development workflow, coding principles, testing guidelines, and PR checklist.

Requirements

• Runtime: Node.js ≥ 20 or Bun ≥ 1.2
• TypeScript: 5.x (ES2022, Node16 modules)

CI

GitHub Actions runs on ubuntu-latest, macos-latest, windows-latest — bun only, no node matrix.

License

MIT — see LICENSE.