浏览器调试 MCP Server

一个基于 Puppeteer 和 Chrome DevTools Protocol (CDP) 的 MCP Server 插件，支持通过持久化浏览器连接进行网页调试、性能分析和内存检测。

功能特性

• Console 异常检查：监听和收集 Console 错误、警告和日志

• 元素状态检查：检查 DOM 元素的属性、样式、可见性和交互性

• 缓存状态检查：获取 LocalStorage、SessionStorage、Cookies 和 IndexedDB 状态

• 性能数据获取：收集 Performance Timeline 和页面加载指标

• 内存堆栈分析：获取堆快照、分析内存使用、跟踪对象分配、检测内存泄漏

• 持久化连接：浏览器实例在 Server 启动时创建，保持运行直到 Server 关闭，提高性能

系统要求

• Node.js 20 或更高版本

• Chrome 或 Chromium 浏览器

安装与配置

在 MCP 客户端（如 Cursor、Claude Desktop 等）的配置文件中添加以下配置：

配置完成后，重启 MCP 客户端即可使用。npx 会自动下载并运行最新版本的包，无需手动安装。

可用工具

1. navigate

导航到指定 URL。

参数：

• url (string, 必需): 要导航到的 URL

示例：

2. get_console_errors

获取 Console 异常和日志。

参数：

• url (string, 可选): 页面 URL，如果未提供则使用当前页面

• level (string, 可选): 日志级别过滤 (error | warning | all)，默认为 all

示例：

3. check_element

检查元素状态（属性、样式、可见性等）。

参数：

• selector (string, 必需): CSS 选择器

• url (string, 可选): 页面 URL

示例：

4. get_cache_status

获取缓存状态（LocalStorage、SessionStorage、Cookies、IndexedDB）。

参数：

• url (string, 可选): 页面 URL

示例：

5. get_performance

获取性能数据（Performance Timeline、页面加载指标）。

参数：

• url (string, 可选): 页面 URL

示例：

6. get_heap_snapshot

获取堆快照。

参数：

• url (string, 可选): 页面 URL

• topN (number, 可选): Top N（构造函数/节点）数量，默认 20

• collectGarbage (boolean, 可选): 采集前是否触发 GC，默认 false

• maxSnapshotBytes (number, 可选): raw snapshot 采集最大字节数，默认 200MB（超出将截断并跳过解析）

• maxParseBytes (number, 可选): JSON.parse 解析最大字节数，默认 50MB（超出将跳过解析）

• export (object, 可选): raw snapshot 导出选项

  • mode ('none' | 'file' | 'inline' | 'both', 可选): 导出方式，默认 none

  • filePath (string, 可选): file/both 模式输出路径；不填则默认写入当前目录下的 ./.heapsnapshot/（服务端会自动创建目录）

  • maxInlineBytes (number, 可选): inline/both 模式 inline 输出最大字节数（超出截断）

示例：

返回（new shape）：

• timestamp: 采集时间戳

• summary: 解析摘要（parsed 为 true 时包含 totalNodes/totalSizeBytes/topConstructors/topNodes）

• export: raw snapshot 导出结果（file/inline/both）

• limitations（可选）: 截断/跳过解析等限制说明

兼容字段（deprecated，计划下个 major 移除）：

• totalSize：请迁移到 summary.totalSizeBytes

• totalNodes：请迁移到 summary.totalNodes

• nodes：为避免响应过大，可能仅返回 TopN 节点（截断）；请迁移到 summary.topNodes（或使用 export.filePath 导出原始快照后再做离线分析）

7. analyze_memory

分析内存使用情况。

参数：

• url (string, 可选): 页面 URL

示例：

8. track_allocations

跟踪对象分配。

参数：

• url (string, 可选): 页面 URL

• duration (number, 可选): 跟踪时长（毫秒），默认 5000

• topN (number, 可选): Top N（调用栈）数量，默认 20

• collectGarbage (boolean, 可选): 采集前是否触发 GC，默认 false

• maxSnapshotBytes (number, 可选): raw profile（带 trace 的 heap snapshot）采集最大字节数，默认 200MB

• maxParseBytes (number, 可选): JSON.parse 解析最大字节数，默认 50MB

• export (object, 可选): raw profile 导出选项（推荐 file，避免响应过大）

  • mode (string, 可选): none | file | inline | both

  • filePath (string, 可选): file/both 模式输出路径（推荐相对路径，如 ./.heapsnapshot/alloc.heapsnapshot）

  • maxInlineBytes (number, 可选): inline/both 模式 inline 最大字节数（超出截断）

示例：

9. take_screenshot

截图（辅助调试）。支持智能输出模式，自动根据图片大小选择返回 base64 或保存为文件，改进的全页截图功能可正确处理懒加载内容。

参数：

• url (string, 可选): 页面 URL（可选）

• fullPage (boolean, 可选): 是否截取整页，默认 false

• outputMode (string, 可选): 输出模式，默认 auto

  • auto：根据图片大小自动选择（小图片返回 base64，大图片保存为文件）

  • file：始终保存为文件，返回路径

  • inline：始终返回 base64（仅用于小图片）

• filePath (string, 可选): 文件保存路径（file/auto 模式使用，默认：./screenshots/screenshot-{timestamp}-{random}.png）

• maxBase64SizeKB (number, 可选): auto 模式阈值（KB，base64 大小，默认 100KB base64 ≈ 75KB 原图）

• scrollDelay (number, 可选): 滚动后等待时间（毫秒，用于触发懒加载，默认 1000）

• waitForSelector (string, 可选): 等待特定选择器加载（可选）

示例：

基本截图（视口）：

全页截图（自动输出模式）：

保存为文件：

返回 base64（小图片）：

等待特定元素加载后截图：

10. get_lighthouse

获取 Lighthouse 性能报告（包括性能、可访问性、最佳实践、SEO 等指标）。

参数：

• url (string, 可选): 页面 URL（可选）

• onlyCategories (string[], 可选): 只分析的类别（可选，如：performance, accessibility, best-practices, seo）

• skipAudits (string[], 可选): 跳过的审计项 ID（可选，如：uses-optimized-images, render-blocking-resources）

示例：

返回结构：

返回的报告中包含以下字段：

• url: 页面 URL

• fetchTime: 报告生成时间

• userAgent: 用户代理字符串

• categories: 类别评分（根据 onlyCategories 参数过滤）

  • performance: 性能评分

  • accessibility: 可访问性评分

  • best-practices: 最佳实践评分

  • seo: SEO 评分

• metrics: 性能指标

  • firstContentfulPaint: 首次内容绘制时间

  • largestContentfulPaint: 最大内容绘制时间

  • totalBlockingTime: 总阻塞时间

  • cumulativeLayoutShift: 累积布局偏移

  • speedIndex: 速度指数

  • timeToInteractive: 可交互时间

  • firstInputDelay: 首次输入延迟

  • timeToFirstByte: 首字节时间

• opportunities: 优化建议（根据 skipAudits 参数过滤）

• diagnostics: 诊断信息（根据 skipAudits 参数过滤）

• implementation: 固定为 "approximation"，表示这是基于 Web Vitals 和 CDP 的近似实现

• limitations: 限制说明数组，包含以下内容：

  • "accessibility/best-practices/seo 评分为近似值，非完整审计"

  • "指标采集基于 Web Vitals 和 CDP，可能与真实 Lighthouse 结果有差异"

  • "部分审计项可能缺失或不完整"

注意事项：

• onlyCategories 参数用于过滤返回的类别，如果未指定则返回所有类别

• skipAudits 参数用于跳过特定的审计项，这些审计项不会出现在 opportunities 和 diagnostics 中

• 返回的评分和指标是基于 Web Vitals 和 CDP 的近似值，可能与真实 Lighthouse 结果有差异

• accessibility、best-practices 和 seo 的评分为占位值，仅供参考

使用示例

检查页面错误

分析页面性能

检查元素状态

内存泄漏检测

Lighthouse 性能分析

注意事项

• 持久化连接：浏览器实例在 Server 启动时创建，保持运行直到 Server 关闭。

• 动态 URL：所有工具都支持通过参数传入 URL。如果页面不存在，系统会自动创建新页面并导航到指定 URL。

• Chrome 路径：如果系统未安装 Chrome 或 Chromium，或安装路径不在默认位置，可以通过 PUPPETEER_EXECUTABLE_PATH 环境变量指定浏览器路径：

  • Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

  • macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

  • Linux: /usr/bin/google-chrome 或 /usr/bin/chromium-browser

许可证

MIT