snapmcp

用于可视化文档的 MCP 服务。
终端 · 代码 · 浏览器 · Markdown · 差异 · HTML · PDF · GIF
面向文档工作流——适用于结构化快照无法满足需求的场景。

真实终端配色、Shiki 代码高亮、可视化差异、PDF 和 GIF——一个 MCP 服务，提供 13 种工具。使用系统 Chrome 渲染，或在首次设置时自动安装 Chromium。默认启用 SSRF 防护。专为编写文档的 Agent 打造，而不只是驱动浏览器。

快速开始

三个步骤，不到两分钟：

1. 安装

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

2. 添加到 Claude Code（~/.claude/claude.json）

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

3. 捕获

用自然语言向 Agent 提出请求：

“捕获 git log --oneline -5 的终端截图，以及 src/index.ts 的语法高亮 PNG。”

Agent 会调用 capture_terminal 和 capture_file——图像会保存到 ./captures/，并应用真实的终端主题和所选的语法主题。

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

效果展示

捕获内容	预览
终端（自动检测真实配色）
代码（Shiki 语法高亮）
差异（绿色/红色）

为什么选择 snapmcp，而不是 Playwright MCP

不同的任务需要不同的工具。Playwright MCP 通过节省令牌的无障碍快照驱动浏览器；snapmcp 则渲染像素级还原的图像，供人阅读。如果 Agent 需要点击，就用 Playwright；如果需要展示，就用 snapmcp。

大多数文档流水线会将两者搭配使用：用 Playwright MCP 交互，用 snapmcp 记录。

工具

使用场景

自动化文档 — Agent 编写设置指南并嵌入真实捕获内容：安装命令的终端输出（采用你的实际主题）、语法高亮的配置文件，以及迁移的差异内容。只需一条提示词和三个 capture_* 调用，图像就会保存到 Markdown 文件旁边。

视觉 QA — UI 更改后，Agent 使用 capture_browser 捕获受影响的页面，使用 capture_batch 批量处理更改前后的截图，并使用 capture_gif 制作动画对比图，用于 PR 描述。

终端指南 — 截图必须与读者实际看到的内容一致的 CLI 教程：capture_terminal 会重现真实的提示符颜色，而不是通用的深色矩形。

安全性

默认启用 SSRF 防护，无需主动开启。

配置

MCP 服务的环境变量：

27 种内置 Shiki 主题：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 除 MCP 服务外，还提供完整的 CLI：

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

文档

开发

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

要求：Node.js ≥ 20 或 Bun ≥ 1.2。CI 通过 GitHub Actions 在 ubuntu / macOS / windows 上运行。

许可证

MIT — 详见 LICENSE。