Webpage Screenshot MCP Server

网页截图 MCP 服务器

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

特征

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

安装

用法

工具

该 MCP 服务器提供了几种工具：

1. 登录并等待

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

• url （必填）：登录页面的 URL
• waitMinutes （可选）：等待登录的最大分钟数（默认值：5）
• successIndicator （可选）：指示登录成功的 CSS 选择器或 URL 模式
• useDefaultBrowser （可选）：是否使用系统默认浏览器（默认值：true）

2. 屏幕截图

捕获给定 URL 的屏幕截图并将其作为 base64 编码图像返回。

• 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. 屏幕截图元素

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

• 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 （可选）：需要清除 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. 后续使用reuseAuthPage: true调用screenshot-page或screenshot-element将使用同一页面
3. 这允许多步骤工作流程，而无需重新进行身份验证

Cookie 管理

您访问的每个域名都会自动保存 Cookie：

1. 使用login-and-wait后，cookie 将保存到主文件夹中的.mcp-screenshot-cookies目录中
2. 当使用useSavedAuth: true再次访问同一域时，会自动加载这些 cookie
3. 您可以使用clear-auth-cookies工具清除 cookies

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

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

1. 手动登录阶段

这将打开您的默认浏览器并显示登录页面。您可以手动登录。登录完成后（无论是检测到登录成功指示，还是离开登录页面），会话 Cookie 都会被保存。

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

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

3. 截取特定元素的屏幕截图

4. 完成后清除 Cookies

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

无头模式与可见模式

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