A Fast Website Screenshot MCP

@just-every/mcp-screenshot-website-fast

快速、高效地截取网页截图——专为命令行编码工具优化。自动将整页切分为 1072x1072 的区块，以便进行最佳处理。

概述

此工具专为 AI 视觉工作流打造，可截取高质量截图，并自动限制分辨率和切分图像，以便 Claude Vision API 及其他 AI 模型进行最佳处理。它可确保截图尺寸精确为 1072x1072 像素（1.15 百万像素），从而实现最佳兼容性。

功能

• 📸 使用 Puppeteer 无头浏览器快速截取截图
• 🎯 针对 Claude Vision 优化，自动限制分辨率（1072x1072，最佳像素数为 1.15 百万）
• 🔲 自动切分——自动将整页拆分为 1072x1072 的区块
• 🎬 录屏截图——按可配置的时间间隔连续截取一系列截图
• 🔄 始终获取最新内容——不使用缓存，确保截图内容为最新
• 📱 可配置视口，用于响应式测试
• ⏱️ 动态内容等待策略（networkidle、自定义延迟）
• 📄 默认截取整页，获取完整页面截图
• 🎥 动态 WebP 导出——将录屏截图保存为高质量动态 WebP 文件
• 💉 JavaScript 注入——在录屏截图前执行自定义 JS
• 📦 依赖项少，npm 安装速度快
• 🔌 MCP 集成，实现无缝 AI 工作流
• 🪟 兼容 Windows 的启动器，适用于通过 npm 安装的 MCP
• 🔋 高效利用资源——闲置 60 秒后自动清理浏览器
• 🧹 内存管理——每次截图后关闭页面，避免内存泄漏

安装

Claude Code

claude mcp add screenshot-website-fast -s user -- npx -y @just-every/mcp-screenshot-website-fast

VS Code

code --add-mcp '{"name":"screenshot-website-fast","command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}'

Cursor

cursor://anysphere.cursor-deeplink/mcp/install?name=screenshot-website-fast&config=eyJzY3JlZW5zaG90LXdlYnNpdGUtZmFzdCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqdXN0LWV2ZXJ5L21jcC1zY3JlZW5zaG90LXdlYnNpdGUtZmFzdCJdfX0=

JetBrains IDEs

设置 → 工具 → AI 助手 → Model Context Protocol (MCP) → 添加

选择“As JSON”并粘贴：

{"command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}

原始 JSON（适用于任何 MCP 客户端）

{
  "mcpServers": {
    "screenshot-website-fast": {
      "command": "npx",
      "args": ["-y", "@just-every/mcp-screenshot-website-fast"]
    }
  }
}

将此内容放入客户端的 mcp.json 中（例如 .vscode/mcp.json、~/.cursor/mcp.json 或 Claude 使用的 .mcp.json）。

先决条件

• Node.js 20.x 或更高版本
• npm 或 npx
• Chrome/Chromium（由 Puppeteer 自动下载）

快速开始

MCP 服务用法

在 IDE 中安装后，即可使用以下工具：

可用工具

• take_screenshot - 捕获网页的高质量截图

  • 参数：
    • url（必填）：要捕获的 HTTP/HTTPS URL
    • width（可选）：视口宽度（像素，最大 1072，默认值：1072）
    • height（可选）：视口高度（像素，最大 1072，默认值：1072）
    • fullPage（可选）：使用平铺方式捕获整页截图（默认值：true）
    • waitUntil（可选）：等待事件：load、domcontentloaded、networkidle0、networkidle2（默认值：domcontentloaded）
    • waitFor（可选）：额外等待时间（毫秒）
    • directory（可选）：保存截图的目录——返回文件路径而非 base64 图片

• capture_selector - 捕获与 CSS 选择器匹配的特定 DOM 元素的截图

  • 参数：
    • url（必填）：要捕获的 HTTP/HTTPS URL
    • selector（必填）：要捕获元素的 CSS 选择器
    • width（可选）：视口宽度（像素，最大 1072，默认值：1072）
    • height（可选）：视口高度（像素，最大 1072，默认值：1072）
    • waitUntil（可选）：等待事件：load、domcontentloaded、networkidle0、networkidle2（默认值：domcontentloaded）
    • waitForMS（可选）：额外等待时间（毫秒）
    • selectorTimeoutMS（可选）：等待选择器出现后再失败的时长（默认值：5000）

使用示例

默认用法（返回 base64 图片）：

take_screenshot(url="https://example.com")

保存到目录（返回文件路径）：

take_screenshot(url="https://example.com", directory="/path/to/screenshots")

捕获特定元素：

capture_selector(url="https://example.com", selector="#main")

使用 directory 参数时：

• 截图会保存为带时间戳的 PNG 文件
• 返回文件路径而非 base64 数据
• 对于平铺截图，每个平铺块都会保存为单独的文件
• 如果目录不存在，会自动创建

take_screencast

连续捕获一系列截图，制作成屏幕录像。仅捕获视口的顶部平铺块（1072x1072）。

参数

• url（必填）：要捕获的 URL
• duration（可选）：总时长（秒，默认值：10）
• interval（可选）：截图间隔（秒，默认值：2）
• jsEvaluate（可选）：开始时要执行的 JavaScript 代码
• waitUntil（可选）：等待策略：'load'、'domcontentloaded'、'networkidle0'、'networkidle2'
• waitForMS（可选）：开始前的额外等待时间
• directory（可选）：保存为动画 WebP 到目录（每隔 1 秒捕获一次）

使用示例

基本屏幕录像（10 秒内捕获 5 帧）：

take_screencast(url="https://example.com")

自定义时间：

take_screencast(url="https://example.com", duration=15, interval=3)

执行 JavaScript：

take_screencast(
  url="https://example.com",
  jsEvaluate="document.body.style.backgroundColor = 'red';"
)

保存为动画 WebP：

take_screencast(url="https://example.com", directory="/path/to/output")

使用 directory 参数时：

• 会创建间隔为 1 秒的动画 WebP
• 单独的帧也会保存为 PNG 文件
• 动画默认无限循环
• WebP 具有出色的画质：
  • 支持全彩（不受 256 色限制）
  • 对网页动画进行高效压缩
  • 非常适合渐变背景和平滑动画
  • 相比 GIF，文件更小且画质更好

开发用法

安装

npm install
npm run build

捕获截图

# Full page with automatic tiling (default)
npm run dev capture https://example.com -o screenshot.png

# Viewport-only screenshot  
npm run dev capture https://example.com --no-full-page -o screenshot.png

# Wait for specific conditions
npm run dev capture https://example.com --wait-until networkidle0 --wait-for 2000 -o screenshot.png

CLI 选项

• -w, --width <pixels> - 视口宽度（最大 1072，默认值：1072）
• -h, --height <pixels> - 视口高度（最大 1072，默认值：1072）
• --no-full-page - 禁用整页捕获和平铺
• --wait-until <event> - 等待事件：load、domcontentloaded、networkidle0、networkidle2
• --wait-for <ms> - 额外等待时间（毫秒）
• -o, --output <path> - 输出文件路径（平铺输出时必填）

自动重启功能

MCP 服务默认包含自动重启功能，以提高可靠性：

• 如果服务崩溃，会自动重启
• 处理未捕获的异常和 Promise 拒绝
• 实现指数退避（1 分钟内最多尝试 10 次）
• 记录所有重启尝试，以便监控
• 妥善处理关闭信号（SIGINT、SIGTERM）

如需在开发/调试时禁用自动重启：

# Run directly without restart wrapper
npm run serve:dev

架构

mcp-screenshot-website-fast/
├── src/
│   ├── internal/       # Core screenshot capture logic
│   ├── utils/          # Logger and utilities
│   ├── index.ts        # CLI entry point
│   ├── serve.ts        # MCP server entry point
│   └── serve-restart.ts # Auto-restart wrapper

开发

# Run in development mode
npm run dev capture https://example.com -o screenshot.png

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

为什么选择此工具？

专为 AI 视觉工作流打造：

1. 针对 Claude Vision API 进行了优化 - 自动将分辨率限制为 1072x1072 像素（1.15 兆像素）
2. 自动分块 - 将完整页面拆分为适合 AI 处理的完美区块
3. 始终获取最新内容 - 不使用缓存，确保获取最新内容
4. 原生支持 MCP - 与 AI 开发工具实现一流集成
5. 简单的 API - 用于截取屏幕截图的简洁直观接口

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交拉取请求

故障排除

Puppeteer 问题

• 确保可以下载 Chrome/Chromium
• 检查防火墙设置
• 尝试设置 PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true 并提供自定义可执行文件

截图质量

• 调整视口尺寸
• 使用适当的等待策略
• 检查网站是否需要身份验证

超时错误

• 使用 --wait-for 标志延长等待时间
• 使用不同的 --wait-until 策略
• 检查网站是否可访问

许可证

MIT