HelloWorld
登录
a

ananddtyagi

web-scrapingbrowser-automation

312 查看 · 2026-07-07 更新

Webpage Screenshot MCP 服务器

这是一个使用 Puppeteer 捕获网页截图的 MCP（Model Context Protocol）服务器。该服务器允许 AI 代理视觉验证 Web 应用程序，并在生成 Web 应用时查看其进度。

Screen Recording May 27 2025 (2)

功能

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

安装

要安装并构建 MCP：

bash

克隆仓库（如果尚未克隆）

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 Desktop 或 Cursor：

  1. Claude Desktop：

    • 转到设置 > 开发者
    • 点击“编辑配置”
    • 添加以下内容：

    json "webpage-screenshot": { "command": "node", "args": [ "~/path/to/webpage-screenshot-mcp/dist/index.js" ] }

    • 保存并重新加载 Claude

  2. Cursor：

    • 打开 Cursor 并转到 Cursor 设置 > MCP
    • 点击“添加新的全局 MCP 服务器”
    • 添加以下内容：

    json "webpage-screenshot": { "command": "node", "args": ["~/path/to/webpage-screenshot-mcp/dist/index.js"] }

    • 保存并重新加载 Cursor

使用

工具

此 MCP 服务器提供了几个工具：

1. login-and-wait

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

json { "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 编码的图像返回。

json { "url": "https://example.com/dashboard", "fullPage": true, "width": 1920, "height": 1080, "format": "png", "quality": 80, "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（可选）：是否使用之前登录保存的 Cookie（默认：true）- reuseAuthPage（可选）：是否使用现有的已认证页面（默认：false）
  • useDefaultBrowser（可选）：是否使用系统的默认浏览器（默认：false）
  • visibleBrowser（可选）：是否显示浏览器窗口（默认：false）

3. screenshot-element

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

json { "url": "https://example.com/dashboard", "selector": ".user-profile", "waitForSelector": true, "format": "png", "quality": 80, "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。

json { "url": "https://example.com" }

  • url（可选）：要清除 cookies 的域名的 URL。如果不提供，则清除所有 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. 手动登录阶段

json { "name": "login-and-wait", "parameters": { "url": "https://example.com/login", "waitMinutes": 3, "successIndicator": ".dashboard-welcome", "useDefaultBrowser": true } }这将打开您的默认浏览器并显示登录页面。您可以手动登录，一旦完成（通过检测成功指示器或离开登录页面后），会话cookie将会被保存。

  1. 使用保存的会话截屏

json { "name": "screenshot-page", "parameters": { "url": "https://example.com/account", "fullPage": true, "useSavedAuth": true, "reuseAuthPage": true, "useDefaultBrowser": true, "visibleBrowser": true } }

这将使用您在相同浏览器窗口中保存的身份验证cookie来对账户页面进行截图。

  1. 对特定元素进行截屏

json { "name": "screenshot-element", "parameters": { "url": "https://example.com/dashboard", "selector": ".user-profile-section", "useSavedAuth": true, "useDefaultBrowser": true, "visibleBrowser": true } }

  1. 完成后清除Cookies

json { "name": "clear-auth-cookies", "parameters": { "url": "https://example.com" } }

此工作流程允许您像普通用户一样与受保护的页面交互，在默认浏览器中完成完整的身份验证流程。

无头模式与可见模式

  • 无头模式 (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 服务器会在控制台记录有用的错误消息。请查看这些消息以获取故障排除信息。

来源