浏览器调试 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 等）的配置文件中添加以下配置：
{
"mcpServers": {
"puppeteer-debugger-mcp": {
"command": "npx",
"args": ["-y", "@aliex7664/puppeteer-debugger-mcp@latest"]
}
}
}
配置完成后，重启 MCP 客户端即可使用。npx 会自动下载并运行最新版本的包，无需手动安装。
可用工具
1. navigate
导航到指定 URL。
参数：
url(string, 必需): 要导航到的 URL
示例：
{
"name": "navigate",
"arguments": {
"url": "https://example.com"
}
}
2. get_console_errors
获取 Console 异常和日志。
参数：
url(string, 可选): 页面 URL，如果未提供则使用当前页面level(string, 可选): 日志级别过滤 (error|warning|all)，默认为all
示例：
{
"name": "get_console_errors",
"arguments": {
"url": "https://example.com",
"level": "error"
}
}
3. check_element
检查元素状态（属性、样式、可见性等）。
参数：
selector(string, 必需): CSS 选择器url(string, 可选): 页面 URL
示例：
{
"name": "check_element",
"arguments": {
"selector": "#my-button",
"url": "https://example.com"
}
}
4. get_cache_status
获取缓存状态（LocalStorage、SessionStorage、Cookies、IndexedDB）。
参数：
url(string, 可选): 页面 URL
示例：
{
"name": "get_cache_status",
"arguments": {
"url": "https://example.com"
}
}
5. get_performance
获取性能数据（Performance Timeline、页面加载指标）。
参数：
url(string, 可选): 页面 URL
示例：
{
"name": "get_performance",
"arguments": {
"url": "https://example.com"
}
}
6. get_heap_snapshot
获取堆快照。
参数：
url(string, 可选): 页面 URLtopN(number, 可选): Top N（构造函数/节点）数量，默认 20collectGarbage(boolean, 可选): 采集前是否触发 GC，默认 falsemaxSnapshotBytes(number, 可选): raw snapshot 采集最大字节数，默认 200MB（超出将截断并跳过解析）maxParseBytes(number, 可选): JSON.parse 解析最大字节数，默认 50MB（超出将跳过解析）export(object, 可选): raw snapshot 导出选项mode('none' | 'file' | 'inline' | 'both', 可选): 导出方式，默认nonefilePath(string, 可选): file/both 模式输出路径；不填则默认写入当前目录下的./.heapsnapshot/（服务端会自动创建目录）maxInlineBytes(number, 可选): inline/both 模式 inline 输出最大字节数（超出截断）
示例：
{
"name": "get_heap_snapshot",
"arguments": {
"url": "https://example.com",
"topN": 20,
"export": {
"mode": "both",
"maxInlineBytes": 65536
}
}
}
返回（new shape）：
timestamp: 采集时间戳summary: 解析摘要（parsed为 true 时包含totalNodes/totalSizeBytes/topConstructors/topNodes）export: raw snapshot 导出结果（file/inline/both）limitations（可选）: 截断/跳过解析等限制说明
兼容字段（deprecated，计划下个 major 移除）：
totalSize：请迁移到summary.totalSizeBytestotalNodes：请迁移到summary.totalNodesnodes：为避免响应过大，可能仅返回 TopN 节点（截断）；请迁移到summary.topNodes（或使用export.filePath导出原始快照后再做离线分析）
7. analyze_memory
分析内存使用情况。
参数：
url(string, 可选): 页面 URL
示例：
{
"name": "analyze_memory",
"arguments": {
"url": "https://example.com"
}
}
8. track_allocations
跟踪对象分配。
参数：
url(string, 可选): 页面 URLduration(number, 可选): 跟踪时长（毫秒），默认 5000topN(number, 可选): Top N（调用栈）数量，默认 20collectGarbage(boolean, 可选): 采集前是否触发 GC，默认 falsemaxSnapshotBytes(number, 可选): raw profile（带 trace 的 heap snapshot）采集最大字节数，默认 200MBmaxParseBytes(number, 可选): JSON.parse 解析最大字节数，默认 50MBexport(object, 可选): raw profile 导出选项（推荐file，避免响应过大）mode(string, 可选):none|file|inline|bothfilePath(string, 可选):file/both模式输出路径（推荐相对路径，如./.heapsnapshot/alloc.heapsnapshot）maxInlineBytes(number, 可选):inline/both模式 inline 最大字节数（超出截断）
示例：
{
"name": "track_allocations",
"arguments": {
"url": "https://example.com",
"duration": 10000,
"topN": 20,
"export": {
"mode": "file",
"filePath": "./.heapsnapshot/alloc-example.heapsnapshot"
}
}
}
9. take_screenshot
截图（辅助调试）。支持智能输出模式，自动根据图片大小选择返回 base64 或保存为文件，改进的全页截图功能可正确处理懒加载内容。
参数：
url(string, 可选): 页面 URL（可选）fullPage(boolean, 可选): 是否截取整页，默认 falseoutputMode(string, 可选): 输出模式，默认autoauto：根据图片大小自动选择（小图片返回 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, 可选): 等待特定选择器加载（可选）
示例：
基本截图（视口）：
{
"name": "take_screenshot",
"arguments": {
"url": "https://example.com"
}
}
全页截图（自动输出模式）：
{
"name": "take_screenshot",
"arguments": {
"url": "https://example.com",
"fullPage": true,
"outputMode": "auto"
}
}
保存为文件：
{
"name": "take_screenshot",
"arguments": {
"url": "https://example.com",
"fullPage": true,
"outputMode": "file",
"filePath": "./screenshots/example.png"
}
}
返回 base64（小图片）：
{
"name": "take_screenshot",
"arguments": {
"url": "https://example.com",
"outputMode": "inline"
}
}
等待特定元素加载后截图：
{
"name": "take_screenshot",
"arguments": {
"url": "https://example.com",
"fullPage": true,
"waitForSelector": ".main-content",
"scrollDelay": 2000
}
}
10. get_lighthouse
获取 Lighthouse 性能报告（包括性能、可访问性、最佳实践、SEO 等指标）。
参数：
url(string, 可选): 页面 URL（可选）onlyCategories(string[], 可选): 只分析的类别（可选，如：performance,accessibility,best-practices,seo）skipAudits(string[], 可选): 跳过的审计项 ID（可选，如：uses-optimized-images,render-blocking-resources）
示例：
{
"name": "get_lighthouse",
"arguments": {
"url": "https://example.com",
"onlyCategories": ["performance", "accessibility"],
"skipAudits": ["uses-optimized-images"]
}
}
返回结构：
返回的报告中包含以下字段：
url: 页面 URLfetchTime: 报告生成时间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的评分为占位值，仅供参考
使用示例
检查页面错误
// 1. 导航到页面
{
"name": "navigate",
"arguments": {
"url": "https://example.com"
}
}
// 2. 获取 Console 错误
{
"name": "get_console_errors",
"arguments": {
"level": "error"
}
}
分析页面性能
{
"name": "get_performance",
"arguments": {
"url": "https://example.com"
}
}
检查元素状态
{
"name": "check_element",
"arguments": {
"selector": "button.submit",
"url": "https://example.com"
}
}
内存泄漏检测
// 获取初始堆快照
{
"name": "get_heap_snapshot",
"arguments": {
"url": "https://example.com"
}
}
// 分析内存使用情况
{
"name": "analyze_memory",
"arguments": {
"url": "https://example.com"
}
}
// 跟踪对象分配
{
"name": "track_allocations",
"arguments": {
"url": "https://example.com",
"duration": 10000
}
}
Lighthouse 性能分析
// 获取完整的 Lighthouse 报告
{
"name": "get_lighthouse",
"arguments": {
"url": "https://example.com"
}
}
// 只分析性能类别
{
"name": "get_lighthouse",
"arguments": {
"url": "https://example.com",
"onlyCategories": ["performance"]
}
}
// 跳过特定审计项
{
"name": "get_lighthouse",
"arguments": {
"url": "https://example.com",
"skipAudits": ["uses-optimized-images", "render-blocking-resources"]
}
}
注意事项
- 持久化连接：浏览器实例在 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
- Windows:
许可证
MIT