金大哥 - webpage-screenshot-mcp MCP 详情

article

README

🚀 网页截图MCP服务器

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

2025年5月27日屏幕录制 (2)

✨ 主要特性

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

📦 安装指南

要安装和构建MCP，请执行以下步骤：

# 克隆仓库（如果尚未克隆）
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，请按以下步骤操作：

Claude Desktop：

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

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

保存并重新加载Claude。

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。这对于以下情况很有用：

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

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

默认浏览器模式的工作原理

启用默认浏览器模式时：

工具将尝试定位系统的默认浏览器（Chrome、Edge等）。
它会启动浏览器，并在随机端口上启用远程调试。
Puppeteer连接到这个浏览器实例，而不是启动自己的实例。
在会话期间，你现有的配置文件、扩展程序和cookie都可用。
浏览器窗口保持可见，以便你可以手动与之交互。

此模式对于需要认证或复杂用户交互的工作流程特别有用。

浏览器持久化

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

使用login-and-wait时，浏览器会话保持打开状态。
后续使用reuseAuthPage: true调用screenshot-page或screenshot-element时，将使用同一页面。
这允许在多步骤工作流程中无需重新认证。

Cookie管理

访问的每个域的cookie会自动保存：

使用login-and-wait后，cookie会保存到主文件夹中的.mcp-screenshot-cookies目录。
使用useSavedAuth: true再次访问同一域时，这些cookie会自动加载。
你可以使用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。

故障排除

常见问题

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

调试

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

webpage-screenshot-mcp