mcp-server-website

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

这是一款专为命令行编码工具优化的网页截图工具，能够快速、高效地截取网页内容。它会自动将整页内容分割成 1072x1072 的小块，以实现最佳处理效果。

🚀 快速开始

此工具专为人工智能视觉工作流程打造，可捕获高质量的屏幕截图，并自动限制分辨率和进行切片处理，以适配 Claude Vision API 和其他人工智能模型。它能确保截图尺寸精确为 1072x1072 像素（115 万像素），从而实现最大兼容性。

必备条件

• 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 图像

使用示例

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

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

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

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

使用 directory 参数时：

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

take_screencast

随着时间的推移捕获一系列截图以创建屏幕录像。仅捕获视口的顶部切片（1072x1072）。

参数

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

使用示例

基本屏幕录像（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 相比，文件大小更小，质量更好

✨ 主要特性

• 📸 快速截图：使用 Puppeteer 无头浏览器实现快速截图
• 🎯 Claude Vision 优化：自动限制分辨率（1072x1072，115 万像素）
• 🔲 自动切片：整页内容自动分割成 1072x1072 的小块
• 🎬 屏幕录像捕获：可按配置的间隔时间记录一系列截图
• 🔄 内容实时更新：无缓存机制确保获取最新截图
• 📱 可配置视口：便于进行响应式测试
• ⏱️ 等待策略：适用于动态内容（networkidle、自定义延迟）
• 📄 默认整页捕获：可捕获完整网页截图
• 🎥 动画 WebP 导出：将屏幕录像保存为高质量的动画 WebP 文件
• 💉 JavaScript 注入：在屏幕录像捕获前执行自定义 JavaScript 代码
• 📦 依赖极少：实现快速 npm 安装
• 🔌 MCP 集成：无缝集成 AI 工作流程
• 🔋 资源高效利用：闲置 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 助手 → 模型上下文协议（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）。

💻 使用示例

基础用法

# 整页自动切片（默认）
npm run dev capture https://example.com -o screenshot.png

# 仅视口截图
npm run dev capture https://example.com --no-full-page -o screenshot.png

# 等待特定条件
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）

如需在开发/调试时不使用自动重启功能：

# 直接运行，不使用重启包装器
npm run serve:dev

架构

mcp-screenshot-website-fast/
├── src/
│   ├── internal/       # 核心截图捕获逻辑
│   ├── utils/          # 日志记录器和实用工具
│   ├── index.ts        # CLI 入口点
│   ├── serve.ts        # MCP 服务器入口点
│   └── serve-restart.ts # 自动重启包装器

开发

# 以开发模式运行
npm run dev capture https://example.com -o screenshot.png

# 生产环境构建
npm run build

# 运行测试
npm test

# 类型检查
npm run typecheck

# 代码检查
npm run lint

为何选择此工具

此工具专为 AI 视觉工作流程而设计：

1. Claude Vision API 优化：自动将分辨率限制为 1072x1072 像素（115 万像素）
2. 自动切片：将整页内容分割成适合 AI 处理的完美小块
3. 内容实时更新：无缓存机制确保获取最新内容
4. MCP 原生支持：与 AI 开发工具实现一流集成
5. 简单 API：提供简洁、直观的截图捕获接口

🤝 贡献代码

欢迎贡献代码！请按以下步骤操作：

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

🛠️ 故障排除

Puppeteer 问题

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

截图质量问题

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

超时错误

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

📄 许可证

本项目采用 MIT 许可证。