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

快速、高效的网页截图捕获工具 - 专为 CLI 编码工具优化。自动将整页切分为 1072x1072 的块，以实现最佳处理效果。

概述

本工具专为 AI 视觉工作流构建，通过自动分辨率限制和分块功能，捕获高质量截图，以供 Claude Vision API 和其他 AI 模型进行最佳处理。它确保截图大小精确控制在 1072x1072 像素（115 万像素），以实现最大兼容性。

Related MCP server: ScreenshotOne MCP Server

特性

• 📸 快速截图捕获：使用 Puppeteer 无头浏览器

• 🎯 Claude Vision 优化：自动分辨率限制（1072x1072，实现最佳的 115 万像素）

• 🔲 自动分块：整页自动拆分为 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 Assistant → 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 像素（115 万像素）

2. 自动分块 - 整页拆分为完美的块，供 AI 处理

3. 始终新鲜 - 无缓存确保获取最新内容

4. MCP 原生 - 与 AI 开发工具的一流集成

5. 简单 API - 简洁明了的截图捕获接口

贡献

欢迎贡献！请：

1. Fork 本仓库

2. 创建功能分支

3. 为新功能添加测试

4. 提交 Pull Request

故障排除

Puppeteer 问题

• 确保可以下载 Chrome/Chromium

• 检查防火墙设置

• 尝试设置 PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true 并提供自定义可执行文件路径

截图质量

• 调整视口尺寸

• 使用适当的等待策略

• 检查网站是否需要身份验证

超时错误

• 使用 --wait-for 标志增加等待时间

• 使用不同的 --wait-until 策略

• 检查网站是否可访问

许可证

MIT