Webpage Screenshot MCP Server

网页截图 MCP 服务

一个使用 Puppeteer 截取网页截图的 MCP（Model Context Protocol）服务。此服务可让 AI Agent 直观地验证 Web 应用，并在生成 Web 应用时查看进度。

功能

• 整页截图：截取整个网页或仅截取视口
• 元素截图：使用 CSS 选择器指定目标元素
• 多种格式：支持 PNG、JPEG 和 WebP 格式
• 自定义选项：设置视口尺寸、图像质量、等待条件和延迟时间
• Base64 编码：以 Base64 编码图像的形式返回截图，便于集成
• 身份验证支持：支持手动登录和 Cookie 持久化
• 默认浏览器集成：使用系统默认浏览器，获得更自然的体验
• 会话持久化：在多步骤工作流中保持浏览器会话开启

安装

快速开始（Claude Desktop 扩展）

将生成的 screenshot-webpage-mcp.dxt 文件拖放到 Claude Desktop 中，即可自动安装！

手动安装

从源代码安装并构建 MCP：

# Clone the repository (if you haven't already)
git clone https://github.com/ananddtyagi/webpage-screenshot-mcp.git
cd webpage-screenshot-mcp

# Install dependencies
npm install

# Build the project
npm run build

MCP 服务使用 TypeScript 构建并编译为 JavaScript。dist 文件夹中包含编译后的 JavaScript 文件。

添加到 Claude 或 Cursor

将此 MCP 添加到 Claude Desktop 或 Cursor：

1. Claude Desktop：

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

    "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

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

{
  "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": 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 选择器截取网页上特定元素的屏幕截图。

{
  "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（可选）：是否使用之前登录时保存的 Cookie（默认值：true）
• useDefaultBrowser（可选）：是否使用系统默认浏览器（默认值：false）
• visibleBrowser（可选）：是否显示浏览器窗口（默认值：false）

4. clear-auth-cookies

清除特定域名或所有域名保存的身份验证 Cookie。

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

• url（可选）：要清除 Cookie 的域名 URL。如果未提供，则清除所有 Cookie。

默认浏览器模式

默认浏览器模式允许你使用系统自带的常规浏览器（Chrome、Edge 等），而不是 Puppeteer 随附的 Chromium。适用于以下场景：

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

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

默认浏览器模式的工作方式

启用默认浏览器模式后：

1. 工具会尝试查找系统默认浏览器（Chrome、Edge 等）
2. 工具会在随机端口上启用远程调试并启动浏览器
3. Puppeteer 会连接到此浏览器实例，而不是启动自己的浏览器
4. 会话期间可以使用现有的个人资料、扩展程序和 Cookie
5. 浏览器窗口会保持可见，你可以手动与其交互

此模式尤其适用于需要身份验证或复杂用户交互的工作流。

浏览器持久化

MCP 服务可以在多次工具调用之间保持浏览器会话：

1. 使用 login-and-wait 时，浏览器会话会保持打开
2. 后续调用 screenshot-page 或 screenshot-element 并设置 reuseAuthPage: true 时，会使用同一个页面
3. 这样无需重新进行身份验证，即可完成多步骤工作流

Cookie 管理

系统会自动为你访问的每个域名保存 Cookie：

1. 使用 login-and-wait 后，Cookie 会保存到主目录中的 .mcp-screenshot-cookies 目录
2. 再次访问同一域名且设置 useSavedAuth: true 时，系统会自动加载这些 Cookie
3. 你可以使用 clear-auth-cookies 工具清除 Cookie

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

以下是截取需要身份验证的页面的工作流示例：

1. 手动登录阶段

{
  "name": "login-and-wait",
  "parameters": {
    "url": "https://example.com/login",
    "waitMinutes": 3,
    "successIndicator": ".dashboard-welcome",
    "useDefaultBrowser": true
  }
}

这会在默认浏览器中打开登录页面。你可以手动登录；登录完成后（无论是检测到成功指示标记，还是离开登录页面后），系统都会保存会话 Cookie。

2. 使用已保存的会话截图

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

这会在同一个浏览器窗口中使用已保存的身份验证 Cookie，截取账户页面。

3. 截取特定元素

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

4. 完成后清除 Cookie

{
  "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 工具清除 Cookie。

调试

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