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 許可證。