Snapmcp 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. Renders with your system Chrome, or auto-installs Chromium at first setup. 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.

{
  "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

What it looks like

Capture	Preview
Terminal (real detected colors)
Code (Shiki syntax)
Diff (green/red)

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.

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

Tools

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.

Configuration

Environment variables for the MCP server:

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

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.