星战科技xingzhan.cloud
返回市场
网页截图-MCP

网页截图-MCP

作者：ananddtyagi45 星标更新：2025-06-29
安装使用来源：spider==github.com

项目介绍

Webpage Screenshot MCP Server

一个使用Puppeteer捕获网页截图的MCP（模型上下文协议）服务器。此服务器允许AI代理通过视觉方式验证Web应用程序，并在生成Web应用时查看其进度。

Screen Recording May 27 2025 (2)

特性

  • 全页截图：捕获整个网页或仅视口部分
  • 元素截图：使用CSS选择器定位特定元素
  • 多种格式支持：支持PNG、JPEG和WebP格式
  • 可定制选项：设置视口大小、图像质量、等待条件和延迟
  • Base64编码：以base64编码的图片形式返回截图，便于集成
  • 认证支持：手动登录和cookie持久化
  • 默认浏览器集成：使用系统默认浏览器获得更自然的体验
  • 会话持久化：保持浏览器会话打开，适用于多步骤工作流

安装

快速开始（Claude桌面扩展）

将生成的screenshot-webpage-mcp.dxt文件拖放到Claude桌面中进行自动安装！

手动安装

要从源代码安装和构建MCP：

# 克隆仓库（如果尚未克隆）
git clone https://github.com/ananddtyagi/webpage-screenshot-mcp.git
cd webpage-screenshot-mcp

# 安装依赖
npm install

# 构建项目
npm run build

该MCP服务器使用TypeScript编写并编译成JavaScript。dist文件夹包含编译后的JavaScript文件。

添加到Claude或Cursor

要将此MCP添加到Claude桌面或Cursor：

  1. Claude桌面：

    • 前往设置 > 开发者
    • 点击“编辑配置”
    • 添加以下内容：
     "webpage-screenshot": {
   "command": "node",
   "args": [
     "~/path/to/webpage-screenshot-mcp/dist/index.js"
   ]
 }
    • 保存并重新加载Claude

  2. Cursor：

    • 打开Cursor并前往Cursor设置 > MCP
    • 点击“添加新的全局MCP服务器”
    • 添加以下内容：
  "webpage-screenshot": {
    "command": "node",
    "args": ["~/path/to/webpage-screenshot-mcp/dist/index.js"]
  }
  • 保存并重新加载Cursor

使用方法

工具

此MCP服务器提供多个工具：

1. login-and-wait

在可见的浏览器窗口中打开网页进行手动登录，等待用户完成登录后保存cookies。

{
  "url": "https://example.com/login",
  "waitMinutes": 5,
  "successIndicator": ".dashboard-welcome",
  "useDefaultBrowser": true
}
  • url（必需）：登录页面的URL
  • waitMinutes（可选）：最大等待时间（默认：5分钟）
  • successIndicator（可选）：表示成功登录的CSS选择器或URL模式
  • useDefaultBrowser（可选）：是否使用系统的默认浏览器（默认：true）

2. screenshot-page

捕获给定URL的截图并以base64编码的图片形式返回。

{
  "url": "https://example.com/dashboard",
  "fullPage": true,
  "width": 1920,
  "height": 1080,
  "format": "png",
  "quality": 100,
  "waitFor": "networkidle2",
  "delay": 500,
  "useSavedAuth": true,
  "reuseAuthPage": true,
  "useDefaultBrowser": true,
  "visibleBrowser": true
}
  • url（必需）：要截图的网页URL
  • fullPage（可选）：是否捕获整个页面或仅视口（默认：true）
  • width（可选）：视口宽度（像素，默认：1920）
  • height（可选）：视口高度（像素，默认：1080）
  • format（可选）：图片格式 - "png", "jpeg", 或 "webp"（默认："png"）
  • quality（可选）：图片质量（0-100），仅适用于jpeg和webp
  • waitFor（可选）：何时认为页面已加载 - "load", "domcontentloaded", "networkidle0", 或 "networkidle2"（默认："networkidle2"）
  • delay（可选）：页面加载后的额外延迟（毫秒，默认：0）
  • useSavedAuth（可选）：是否使用之前登录保存的cookies（默认：true）
  • reuseAuthPage（可选）：是否使用已存在的认证页面（默认：false）
  • useDefaultBrowser（可选）：是否使用系统的默认浏览器（默认：false）
  • visibleBrowser（可选）：是否显示浏览器窗口（默认：false）

3. screenshot-element

使用CSS选择器捕获网页上特定元素的截图。

{
  "url": "https://example.com/dashboard",
  "selector": ".user-profile",
  "waitForSelector": true,
  "format": "png",
  "quality": 100,
  "padding": 10,
  "useSavedAuth": true,
  "useDefaultBrowser": true,
  "visibleBrowser": true
}
  • url（必需）：网页的URL
  • selector（必需）：用于截图的元素的CSS选择器
  • waitForSelector（可选）：是否等待选择器出现（默认：true）
  • format（可选）：图片格式 - "png", "jpeg", 或 "webp"（默认："png"）
  • quality（可选）：图片质量（0-100），仅适用于jpeg和webp
  • padding（可选）：元素周围的填充（像素，默认：0）
  • useSavedAuth（可选）：是否使用之前登录保存的cookies（默认：true）
  • useDefaultBrowser（可选）：是否使用系统的默认浏览器（默认：false）
  • visibleBrowser（可选）：是否显示浏览器窗口（默认：false）

4. clear-auth-cookies

清除特定域或所有域的保存认证cookies。

{
  "url": "https://example.com"
}
  • url（可选）：要清除cookies的域名。如果没有提供，则清除所有cookies。

默认浏览器模式

默认浏览器模式允许您使用系统的常规浏览器（如Chrome、Edge等）而不是Puppeteer捆绑的Chromium。这对于以下情况非常有用：

  1. 使用现有的浏览器会话和扩展
  2. 使用保存的凭据手动登录网站
  3. 对于多步骤工作流，具有更自然的浏览体验
  4. 使用与用户相同的浏览器环境进行测试

要启用默认浏览器模式，在您的工具参数中设置useDefaultBrowser: true和visibleBrowser: true。

默认浏览器模式的工作原理

当您启用默认浏览器模式时：

  1. 工具将尝试找到系统的默认浏览器（如Chrome、Edge等）
  2. 在随机端口上启用远程调试启动您的浏览器
  3. Puppeteer连接到这个浏览器实例而不是启动自己的
  4. 您现有的配置文件、扩展和cookies在会话期间可用
  5. 浏览器窗口保持可见，以便您可以手动与其交互

这种模式特别适合需要身份验证或复杂用户交互的工作流。

浏览器持久化

MCP服务器可以在多个工具调用之间维持持久的浏览器会话：

  1. 当您使用login-and-wait时，浏览器会话保持打开
  2. 后续调用screenshot-page或screenshot-element时，如果设置了reuseAuthPage: true，则使用同一页面
  3. 这允许多步骤工作流而无需重新认证

Cookie管理

每次访问的域都会自动保存cookies：

  1. 使用login-and-wait之后，cookies会被保存到家目录下的.mcp-screenshot-cookies目录
  2. 再次访问同一域时，如果设置了useSavedAuth: true，这些cookies会自动加载
  3. 您可以使用clear-auth-cookies工具清除cookies

示例工作流：受保护页面的截图

这是一个示例工作流，用于获取需要身份验证的页面的截图：

  1. 手动登录阶段
{
  "name": "login-and-wait",
  "parameters": {
    "url": "https://example.com/login",
    "waitMinutes": 3,
    "successIndicator": ".dashboard-welcome",
    "useDefaultBrowser": true
  }
}

这将在您的默认浏览器中打开登录页面。您可以手动登录，一旦完成（通过检测成功指示器或导航离开登录页面），会话cookies将被保存。

  1. 使用保存的会话截图
{
  "name": "screenshot-page",
  "parameters": {
    "url": "https://example.com/account",
    "fullPage": true,
    "useSavedAuth": true,
    "reuseAuthPage": true,
    "useDefaultBrowser": true,
    "visibleBrowser": true
  }
}

这将使用您保存的身份验证cookies在同一浏览器窗口中截取账户页面的截图。

  1. 特定元素的截图
{
  "name": "screenshot-element",
  "parameters": {
    "url": "https://example.com/dashboard",
    "selector": ".user-profile-section",
    "useSavedAuth": true,
    "useDefaultBrowser": true,
    "visibleBrowser": true
  }
}
  1. 完成后清除cookies
{
  "name": "clear-auth-cookies",
  "parameters": {
    "url": "https://example.com"
  }
}

此工作流允许您像普通用户一样与受保护的页面互动，完成完整的身份验证流程。

无头模式 vs. 可见模式

  • 无头模式（visibleBrowser: false）：更快，更适合不需要用户交互的自动化工作流。
  • 可见模式（visibleBrowser: true）：显示浏览器窗口，允许用户交互和手动验证。要求useDefaultBrowser: true。

平台支持

默认浏览器检测支持：

  • macOS：检测Chrome、Edge和Safari
  • Windows：通过注册表或常见安装路径检测Chrome和Edge
  • Linux：通过系统命令检测Chrome和Chromium

故障排除

常见问题

  1. 未找到默认浏览器：如果系统找不到您的默认浏览器，它将回退到Puppeteer捆绑的Chromium。
  2. 连接问题：如果连接到浏览器调试端口出现问题，请检查是否有其他实例正在使用该端口。
  3. Cookie问题：如果身份验证不起作用，请尝试使用clear-auth-cookies工具清除cookies。

调试

当出现问题时，MCP服务器会在控制台记录有用的错误消息。检查这些消息以获取故障排除信息。