Webpage Screenshot MCP

🚀 网页截图MCP服务器

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

✨ 主要特性

• 全页截图：可捕获整个网页或仅视口区域。
• 元素截图：使用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，请按以下步骤操作：

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. 后续使用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工具清除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服务器会在控制台记录有用的错误消息。检查这些消息以获取故障排除信息。