BrowserLoop MCP

BrowserLoop

⚠️ 已存档： 此项目已存档，将不会收到任何进一步的更新。随着 Chrome开发工具MCP，不再需要用于浏览器自动化的专用MCP服务器，因为该项目提供了更全面的浏览器交互功能，包括屏幕截图、控制台监控等等。

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

注： 此存储库中的几乎所有代码都是自动生成的。这意味着你可能不应该太信任它。话虽如此，它确实有效，我自己也在使用它。

注： 如果文档不正确，请告诉我或发送PR。如果您也想使用代码生成工具更新此项目的代码， PROJECT_CONTEXT.md 已被用作背景，以很好地概述项目的各个部分。现在可能有点混乱，但这是一个很好的起点，欢迎您对其进行更新。

特性

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

快速开始

📦 NPX用法（推荐）

最简单的入门方法-无需安装！

# Install Chromium browser (one-time setup)
npx playwright install chromium

# Test that BrowserLoop works
npx browserloop@latest --version

就是这样！ 最新版本的BrowserLoop将自动下载并执行。非常适合想要零维护截图的MCP用户。

MCP配置

将BrowserLoop添加到MCP配置文件中（例如。 ~/.cursor/mcp.json):

{
  "mcpServers": {
    "browserloop": {
      "command": "npx",
      "args": ["-y", "browserloop@latest"],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

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

🚀 光标一键安装

使用此深度链接单击一下即可将BrowserLoop添加到Cursor：

🔗 将BrowserLoop添加到游标

此深度链接将使用npx和最新版本在您的游标MCP设置中自动配置BrowserLoop，使其具有最佳配置。

先决条件： 请确保您首先安装了Chromium：

npx playwright install chromium

浏览器安装要求

🚨 严重： BrowserLoop需要通过Playwright安装Chromium才能截图。

首次设置（所有用户）

安装Chromium浏览器：

npx playwright install chromium

验证安装：

# Check Playwright installation
npx playwright --version

# Test BrowserLoop (if using NPX)
npx browserloop@latest --version

🐳 Docker替代品

对于容器化环境：

# Pull and run with Docker
docker run --rm --network host browserloop

# Or use docker-compose for development
git clone 
cd browserloop
docker-compose -f docker/docker-compose.yml up

💻 开发安装

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

# Clone the repository
git clone 
cd browserloop

# Install dependencies
npm install

# Install Playwright browsers (required for screenshots)
npx playwright install chromium
# OR use the convenient script:
npm run install-browsers

# Build the project
npm run build

MCP开发配置

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

替换 /absolute/path/to/browserloop/ 根据您的实际项目路径。

基本用法

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

截图

Take a screenshot of https://example.com
Take a screenshot of https://example.com with width 1920 and height 1080
Take a screenshot of https://example.com in JPEG format with 95% quality
Take a full page screenshot of https://example.com
Take a screenshot of http://localhost:3000 to verify the UI changes

控制台日志读取

Read console logs from https://example.com
Check for console errors on https://example.com
Monitor console warnings from http://localhost:3000
Read only error and warning logs from https://example.com
Capture console output from https://example.com for debugging

🔐 Cookie身份验证

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

Take a screenshot of http://localhost:3000/admin/dashboard using these cookies: [{"name":"connect.sid","value":"s:session-id.signature","domain":"localhost"}]

📖 有关cookie提取方法和开发工作流程，请参阅：

📖 Cookie身份验证指南

常见开发用例：

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

文档

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

API关键参数

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

配置

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

基本配置

验证配置

控制台日志配置

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

原木消毒

控制台日志清理 默认启用 (BROWSERLOOP_SANITIZE_LOGS=true)保护敏感信息。启用后，将自动屏蔽以下模式：

禁用消毒 （用于调试）：

BROWSERLOOP_SANITIZE_LOGS=false

备注：消毒保留了日志结构，同时屏蔽了敏感内容，使日志可以安全地共享和分析。

性能和可靠性

日志记录和调试

调试日志记录

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

• Cookie文件加载和自动刷新事件
• 文件观看状态和娱乐活动
• 截图操作详情
• 配置更改和错误

实时监控日志：

tail -f /tmp/browserloop.log

备注：日志被写入文件（不是控制台），以保持与MCP的stdio协议的兼容性。

使用默认Cookie的MCP配置示例

方法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"
      }
    }
  }
}

控制台日志配置示例

# Only capture warnings and errors
BROWSERLOOP_CONSOLE_LOG_LEVELS="warn,error"

# Debug mode with all logs, no sanitization
BROWSERLOOP_DEBUG="true"
BROWSERLOOP_SANITIZE_LOGS="false"
BROWSERLOOP_CONSOLE_LOG_LEVELS="log,info,warn,error,debug"

故障排除

常见问题

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

# Install Chromium browser (most common fix)
npx playwright install chromium

MCP服务器未启动

1. 手动测试: npx browserloop@latest --version
2. 验证要求:

- Node.js 20+： node --version - npm： npm --version - npx： npx --version

1. 检查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
• 对于localhost：确保您的开发服务器正在运行
• 检查防火墙设置

更新BrowserLoop

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

快速诊断

# Test complete setup
node --version && npm --version
npx playwright --version

# Test BrowserLoop
npx browserloop@latest --version

启用调试日志记录： 集 BROWSERLOOP_DEBUG=true 在MCP配置和监视器中 /tmp/browserloop.log

📖 看 docs/neneneba API.md#错误-绑定 了解详细的故障排除。

许可证

BrowserLoop根据 GNU Affero通用公共许可证v3.0或更高版本（AGPL-3.0或更高）.

这意味着：

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

网络服务

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

1. 向您服务的所有用户提供完整的源代码
2. 包括一个关于用户如何访问源的突出通知
3. 为整个服务使用兼容的许可证

许可证文件

• 许可证 -完整许可证文本

商业用途

组织可以将AGPL下的BrowserLoop用于商业目的，但必须遵守copyleft要求。如果您需要将修改保密，请考虑：

1. 无需修改即可使用BrowserLoop
2. 为社区做出贡献
3. 联系维护人员了解潜在的替代许可安排

有关许可的问题，请打开问题或联系维护人员。