金大哥 - browserloop MCP 详情

article

README

🚀 BrowserLoop

BrowserLoop 是一个基于 Playwright 的模型上下文协议（MCP）服务器，可用于截取网页截图并读取控制台日志。该工具允许 AI 代理自动捕获截图并监控浏览器控制台输出，以进行调试、测试和开发任务。

🚀 快速开始

📦 NPX 使用方法（推荐）

这是最简便的入门方式，无需安装！

# 安装 Chromium 浏览器（一次性设置）
npx playwright install chromium

# 测试 BrowserLoop 是否正常工作
npx browserloop@latest --version

就这么简单！ 最新版本的 BrowserLoop 将自动下载并执行。非常适合希望零维护即可使用截图功能的 MCP 用户。

MCP 配置

将 BrowserLoop 添加到你的 MCP 配置文件（例如 ~/.cursor/mcp.json）中：

{
  "mcpServers": {
    "browserloop": {
      "command": "npx",
      "args": ["-y", "browserloop@latest"],
      "description": "使用 Playwright 进行网页截图和控制台日志捕获的服务器"
    }
  }
}

💡 使用 @latest 可确保你始终自动获得最新功能和错误修复。

🚀 一键安装到 Cursor

使用此深度链接，一键将 BrowserLoop 添加到 Cursor： 🔗 将 BrowserLoop 添加到 Cursor 此深度链接将使用 npx 和最新版本，自动在你的 Cursor MCP 设置中配置 BrowserLoop。 前提条件： 请确保你首先安装了 Chromium：

npx playwright install chromium

浏览器安装要求

🚨 重要提示： 在使用 BrowserLoop 进行截图之前，需要通过 Playwright 安装 Chromium 浏览器。

首次设置（所有用户）

安装 Chromium 浏览器：

npx playwright install chromium

验证安装：

# 检查 Playwright 安装情况
npx playwright --version

# 测试 BrowserLoop（如果使用 NPX）
npx browserloop@latest --version

🐳 Docker 替代方案

对于容器化环境：

# 使用 Docker 拉取并运行
docker run --rm --network host browserloop

# 或者在开发时使用 docker-compose
git clone <repository-url>
cd browserloop
docker-compose -f docker/docker-compose.yml up

💻 开发安装

对于贡献者或希望从源代码构建的高级用户：

# 克隆仓库
git clone <repository-url>
cd browserloop

# 安装依赖项
npm install

# 安装 Playwright 浏览器（截图所需）
npx playwright install chromium
# 或者使用便捷脚本：
npm run install-browsers

# 构建项目
npm run build

开发环境的 MCP 配置

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "使用 Playwright 进行网页截图和控制台日志捕获的服务器"
    }
  }
}

请将 /absolute/path/to/browserloop/ 替换为你实际的项目路径。

基本用法

配置完成后，你可以在 AI 工具中使用自然语言命令：

截图

截取 https://example.com 的屏幕截图
截取宽度为 1920、高度为 1080 的 https://example.com 屏幕截图
以 95% 的质量截取 JPEG 格式的 https://example.com 屏幕截图
截取 https://example.com 的全页屏幕截图
截取 http://localhost:3000 的屏幕截图以验证 UI 更改

读取控制台日志

读取 https://example.com 的控制台日志
检查 https://example.com 上的控制台错误
监控 http://localhost:3000 的控制台警告
仅读取 https://example.com 的错误和警告日志
捕获 https://example.com 的控制台输出以进行调试

🔐 基于 Cookie 的身份验证

BrowserLoop 支持基于 Cookie 的身份验证，可在开发过程中截取受登录保护页面的屏幕截图：

使用以下 Cookie 截取 http://localhost:3000/admin/dashboard 的屏幕截图： [{"name":"connect.sid","value":"s:session-id.signature","domain":"localhost"}]

📖 有关 Cookie 提取方法和开发工作流程，请参阅： 📖 Cookie 身份验证指南 常见的开发用例包括：

具有身份验证的本地开发服务器
暂存环境测试
API 文档工具（Swagger、GraphQL Playground）
开发过程中的自定义 Web 应用程序
管理面板和受保护的路由

✨ 主要特性

📸 使用 Playwright 进行高质量截图捕获
📝 监控和收集网页的控制台日志
🌐 支持本地主机和远程 URL
🍪 受保护页面的基于 Cookie 的身份验证
🐳 Docker 容器化，确保环境一致
⚡ 支持 PNG、JPEG 和 WebP 格式，并可配置质量
🛡️ 以非根用户身份安全执行容器
🤖 与 AI 开发工具完全集成 MCP 协议
🔧 可配置视口大小和捕获选项
📱 支持全页和特定元素的截图捕获
⚠️ 捕获浏览器警告和错误（Permissions-Policy、安全警告）
⚡ 使用 TypeScript 和 Biome 进行快速开发
🧪 使用 Node.js 内置测试运行器进行全面测试

💻 使用示例

基础用法

# 安装 Chromium 浏览器（一次性设置）
npx playwright install chromium

# 测试 BrowserLoop 是否正常工作
npx browserloop@latest --version

高级用法

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "使用 Playwright 进行网页截图和控制台日志捕获的服务器"
    }
  }
}

📚 详细文档

🔐 Cookie 身份验证指南 - 经过身份验证的截图的完整指南
📚 完整 API 参考 - 详细的参数文档、示例和响应格式

关键 API 参数

| 属性 | 详情 | |------|------| | url | 要捕获的目标 URL（必需） | | width | 视口宽度（200 - 4000），默认值为 1280 | | height | 视口高度（200 - 4000），默认值为 720 | | format | 图像格式（webp、png、jpeg），默认值为 webp | | quality | 图像质量（1 - 100），默认值为 80 | | fullPage | 是否捕获全页，默认值为 false | | selector | 用于元素捕获的 CSS 选择器 |

📖 有关完整的参数详细信息、使用示例和配置选项，请参阅 docs/API.md。

🔧 技术细节

配置

BrowserLoop 可以使用环境变量进行配置：

基本配置

| 变量 | 默认值 | 描述 | |----------|---------|-------------| | BROWSERLOOP_DEFAULT_WIDTH | 1280 | 默认视口宽度（200 - 4000） | | BROWSERLOOP_DEFAULT_HEIGHT | 720 | 默认视口高度（200 - 4000） | | BROWSERLOOP_DEFAULT_FORMAT | webp | 默认图像格式（webp、png、jpeg） | | BROWSERLOOP_DEFAULT_QUALITY | 80 | 默认图像质量（0 - 100） | | BROWSERLOOP_DEFAULT_TIMEOUT | 30000 | 默认超时时间（毫秒） | | BROWSERLOOP_USER_AGENT | - | 自定义用户代理字符串 |

身份验证配置

| 变量 | 默认值 | 描述 | |----------|---------|-------------| | BROWSERLOOP_DEFAULT_COOKIES | - | 默认 Cookie，作为文件路径或 JSON 字符串（请参阅 Cookie 身份验证指南） |

控制台日志配置

| 变量 | 默认值 | 描述 | |----------|---------|-------------| | BROWSERLOOP_CONSOLE_LOG_LEVELS | log,info,warn,error,debug | 要捕获的日志级别，以逗号分隔 | | BROWSERLOOP_CONSOLE_TIMEOUT | 30000 | 页面导航超时时间（毫秒，不是日志收集时间） | | BROWSERLOOP_SANITIZE_LOGS | true | 启用/禁用日志中敏感数据的清理 | | BROWSERLOOP_CONSOLE_WAIT_NETWORK_IDLE | true | 在完成收集之前等待网络空闲 | | BROWSERLOOP_MAX_LOG_SIZE | 1048576 | 日志的最大总大小（字节，1MB） |

注意： 控制台日志收集在页面加载后总是精确等待 3 秒以捕获控制台消息。超时设置仅影响页面最初加载的时间。

日志清理

控制台日志清理默认启用（BROWSERLOOP_SANITIZE_LOGS=true），以保护敏感信息。启用后，以下模式将自动屏蔽： | 模式类型 | 示例输入 | 屏蔽输出 | |-------------|---------------|---------------| | API 密钥 | sk_live_1234567890abcdef... | [API_KEY_MASKED] | | 电子邮件地址 | user@example.com | [EMAIL_MASKED] | | JWT 令牌 | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... | [JWT_TOKEN_MASKED] | | 身份验证标头 | Bearer abc123token... | [AUTH_HEADER_MASKED] | | 带有身份验证的 URL | https://api.com/data?token=secret123 | [URL_WITH_AUTH_MASKED] | | 秘密变量 | password: mySecretPass | password: [VALUE_MASKED] |

要禁用清理功能（用于调试）：

BROWSERLOOP_SANITIZE_LOGS=false

注意： 清理功能在屏蔽敏感内容的同时保留日志结构，使日志可安全共享和分析。

性能和可靠性

| 变量 | 默认值 | 描述 | |----------|---------|-------------| | BROWSERLOOP_RETRY_COUNT | 3 | 失败操作的重试次数 | | BROWSERLOOP_RETRY_DELAY | 1000 | 重试之间的延迟（毫秒） |

日志记录和调试

| 变量 | 默认值 | 描述 | |----------|---------|-------------| | BROWSERLOOP_DEBUG | false | 启用调试日志记录到 /tmp/browserloop.log | | BROWSERLOOP_ENABLE_METRICS | true | 启用错误指标收集 | | BROWSERLOOP_DISABLE_FILE_WATCHING | false | 禁用自动 Cookie 文件监控 |

调试日志记录

当 BROWSERLOOP_DEBUG=true 时，详细日志将写入 /tmp/browserloop.log，包括：

Cookie 文件加载和自动刷新事件
文件监控状态和重新创建事件
截图操作详细信息
配置更改和错误

实时监控日志：

tail -f /tmp/browserloop.log

注意： 日志写入文件（而非控制台），以保持与 MCP 的标准输入输出协议的兼容性。

示例 MCP 配置（使用默认 Cookie）

方法 1：JSON 文件（推荐）

创建一个 Cookie 文件：

// ~/.config/browserloop/cookies.json
[
  {
    "name": "connect.sid",
    "value": "s:your-dev-session.signature",
    "domain": "localhost"
  }
]

在 MCP 配置中引用：

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "/home/username/.config/browserloop/cookies.json",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

方法 2：JSON 字符串（旧方法）

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "[{\"name\":\"session_id\",\"value\":\"your_session_value\",\"domain\":\"example.com\"},{\"name\":\"auth_token\",\"value\":\"your_auth_token\"}]",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

控制台日志配置示例

# 仅捕获警告和错误
BROWSERLOOP_CONSOLE_LOG_LEVELS="warn,error"

# 调试模式，记录所有日志，不进行清理
BROWSERLOOP_DEBUG="true"
BROWSERLOOP_SANITIZE_LOGS="false"
BROWSERLOOP_CONSOLE_LOG_LEVELS="log,info,warn,error,debug"

🔍 故障排除

常见问题

“可执行文件不存在”错误

# 安装 Chromium 浏览器（最常见的修复方法）
npx playwright install chromium

MCP 服务器无法启动

手动测试：npx browserloop@latest --version
验证要求：
- Node.js 20+：node --version
- npm：npm --version
- npx：npx --version
检查 MCP 配置 JSON 语法

截图显示登录页面

使用基于 Cookie 的身份验证（请参阅 Cookie 身份验证指南）
检查 Cookie 过期时间和域名设置

控制台日志为空

一些生产网站没有控制台输出（这是正常的）
使用有控制台活动的开发网站进行测试
启用调试日志：BROWSERLOOP_DEBUG=true，并检查 /tmp/browserloop.log
检查日志级别过滤：BROWSERLOOP_CONSOLE_LOG_LEVELS=log,info,warn,error,debug

控制台日志收集时间

收集总是在页面加载后精确等待 3 秒
BROWSERLOOP_CONSOLE_TIMEOUT 控制页面加载超时时间，而非日志收集时间
快速网站总共仍需要约 3 - 4 秒（加载 + 3 秒收集 + 处理）

网络/连接问题

首先使用外部 URL 进行测试：https://example.com
对于本地主机：确保你的开发服务器正在运行
检查防火墙设置

更新 BrowserLoop

NPX：使用 @latest 自动使用最新版本，无需手动更新！
检查当前版本：npx browserloop@latest --version

快速诊断

# 测试完整设置
node --version && npm --version
npx playwright --version

# 测试 BrowserLoop
npx browserloop@latest --version

启用调试日志： 在你的 MCP 配置中设置 BROWSERLOOP_DEBUG=true，并监控 /tmp/browserloop.log 📖 有关详细的故障排除信息，请参阅 docs/API.md#error-handling。

📄 许可证

BrowserLoop 采用 GNU Affero 通用公共许可证 v3.0 或更高版本（AGPL - 3.0 - or - later） 进行许可。

这意味着：

✅ 免费使用 - 允许个人和商业使用
✅ 免费修改 - 你可以根据需要调整代码
✅ 免费分发 - 可以与他人共享副本
✅ 专利保护 - 贡献者提供专利授权
⚠️ Copyleft - 衍生作品也必须在 AGPL - 3.0 下开源
⚠️ 网络条款 - 如果你在服务器上运行修改后的版本，必须向用户提供源代码

对于网络服务

重要提示： 如果你修改了 BrowserLoop 并将其作为网络服务运行（例如，Web 应用程序、API 服务器或云服务），AGPL 要求你：

向服务的所有用户提供完整的源代码
显著通知用户如何访问源代码
对整个服务使用兼容的许可证

许可证文件

LICENSE - 完整的许可证文本

商业使用

组织可以在 AGPL 许可下将 BrowserLoop 用于商业目的，但必须遵守 Copyleft 要求。如果你需要保留修改的隐私性，可以考虑：

使用未修改的 BrowserLoop
将改进贡献回社区
联系维护者了解潜在的替代许可安排有关许可问题，请打开一个问题或联系维护者。