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

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

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

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

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

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:

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

snapmcp doctor

Runs 7 checks:

1. Node.js version ≥ 18
2. Playwright Chromium installed
3. Output directory writable
4. SnapMCP version
5. Chrome/Chromium detected
6. System terminal theme detected
7. 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:

Real Fidelity

SnapMCP detects your real environment for authentic captures.

Terminal auto-detection (in priority order):

Browser auto-detection (in priority order):

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

Security

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

Architecture

src/
├── index.ts        — MCP server, 12 tool definitions, CLI entry
├── renderer.ts     — Capture engine (terminal, code, browser, PDF, GIF)
├── config.ts       — Config loader, defaults, 27 themes
├── cli.ts          — CLI commands (init, doctor, test)
├── security.ts     — SSRF denylist, 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)

Development

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

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 ≥ 18 or Bun ≥ 1.0
• 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.