AI导哈

网页截图服务

一个基于Puppeteer的MCP服务器，提供网页截图功能，支持全页截图、元素截图、多种格式输出和自定义选项，适用于AI代理视觉验证和网页应用开发。

  • by ananddtyagi
  • JavaScript
  • 本地部署
  • 55 星标
  • 更新于
在 GitHub 查看 ananddtyagi/webpage-screenshot-mcp

使用说明

网页截图MCP服务器

使用Puppeteer捕获网页截图的MCP（模型上下文协议）服务器。此服务器允许AI代理在生成web应用程序时直观地验证web应用程序并查看其进度。

特性

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

安装

快速入门（Claude桌面扩展）

拖放生成的 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添加到克劳德桌面或光标：

  1. 克劳德桌面:

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

  2. 光标:

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

用法

工具

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

1.登录并等待

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

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

2.截图页面

捕获给定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”或“networkidles2”（默认值：“networkidlet2”）
  • delay （可选）：页面加载后的额外延迟（毫秒）（默认值：0）
  • useSavedAuth （可选）：是否使用上次登录时保存的Cookie（默认值：true）
  • reuseAuthPage （可选）：是否使用现有的已验证页面（默认值：false）
  • useDefaultBrowser （可选）：是否使用系统的默认浏览器（默认值：false）
  • visibleBrowser （可选）：是否显示浏览器窗口（默认值：false）

3.截图元素

使用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.清除身份验证Cookie

清除特定域或所有域的已保存身份验证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. 当再次访问同一域名时，这些Cookie会自动加载 useSavedAuth: true
  3. 您可以使用 clear-auth-cookies 工具

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

以下是一个示例工作流程，用于对需要身份验证的页面进行截图：

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

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

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

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

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

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

无头模式与可见模式

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

平台支持

默认浏览器检测工作于：

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

故障排除

常见问题

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

调试

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

相关 MCP