Webpage Screenshot MCP Server

网页截图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

1. 光标:

- 打开光标并转到光标设置>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服务器会将有用的错误消息记录到控制台。查看这些消息以获取故障排除信息。