Browserless

Browserless MCP 服务

面向 Browserless.io 的 MCP（Model Context Protocol）服务 — 向 Claude Desktop、Cursor、VS Code 和 Windsurf 等大模型客户端提供 Browserless 智能抓取 API。

快速开始

从 browserless.io 获取 API 令牌（提供免费套餐），然后将 MCP 客户端指向托管服务：

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

无需本地安装 — 各客户端的配置片段请参阅配置。

工具

工具	描述
browserless_smartscraper	抓取单个网页，并以 Markdown 或 HTML 格式返回其内容。自动处理 JavaScript 密集型页面和反机器人措施。若要获取多个页面的内容，请使用 browserless_crawl；若要列出网站的 URL，请使用 browserless_map。
browserless_search	使用 Browserless 搜索网页，并可选择抓取每条结果。支持网页、新闻和图片搜索，并支持地理位置定位和时间筛选。
browserless_map	发现并映射网站上的所有 URL。通过站点地图和链接提取进行扫描。返回 URL，以及可选的标题和描述。适用于网站审查和内容发现。
browserless_crawl	爬取网站并抓取所有发现的页面。支持深度控制、路径筛选、站点地图策略和可配置的抓取选项。返回每个页面的抓取内容和元数据。
browserless_performance	对任意 URL 运行 Lighthouse 审计。内联返回各类别评分，并将完整 JSON 报告保存到对话之外：本地路径（stdio）或经过身份验证的一次性下载 URL（HTTP）。将报告下载到磁盘，并使用 jq 检查所需字段；文件会在 15 分钟后或 MCP 会话结束时过期。还可按类别筛选、模拟移动设备或桌面设备、提供自定义 Lighthouse 配置，或指定性能预算。
browserless_function	在 Browserless 云端执行自定义 Puppeteer JavaScript。该函数接收一个 page 对象和可选的 context；返回 { data, type } 以控制负载和 Content-Type。
browserless_export	通过 Browserless /export API 导出网页。获取 URL 并返回其原生内容（HTML、PDF、图片等），自动检测内容类型。
browserless_agent	通过 ReAct 循环控制持久化浏览器会话：捕获页面快照、规划、批量执行交互（点击、输入、滚动、评估等），然后重新捕获快照。使用根据快照生成的基于引用的选择器，支持多标签页工作流、截图、验证码求解、实时 URL，以及文件上传和下载（捕获的下载会自动显示为句柄；字节内容不会进入上下文）。
browserless_skill	加载按需使用的操作指南，用于处理复杂的页面机制（shadow DOM、Cookie 同意提示、模态框、验证码、动态内容、快照遗漏、截图、标签页）。与 browserless_agent 配套使用。
browserless_profiles	列出为当前令牌保存的身份验证配置，以及 Cookie 和来源数量。将某个配置的名称作为 profile 传递给其他工具，即可复用其登录状态。
browserless_account	读取当前令牌对应的账户信息：套餐、单位余额、计费周期和 API 密钥名称。绝不会返回 API 令牌值。
browserless_usage	读取请求和单位用量：成功数、错误数、超时次数、排队情况、并发峰值、验证码、代理流量字节数和单位数。还可限定到特定 API 密钥。
browserless_sessions	检查账户的会话：当前运行的浏览器、专用工作器上的持久化会话、录制的会话回放，以及 1Password 凭据集成。还可将回放下载为完全自包含的 rrweb 播放器页面（action: "replay"），无需网络即可渲染：服务器在本地运行时，可在浏览器中打开；否则，如果内容足够小，可作为内联 HTML 资源附加。
browserless_logs	读取 Browserless 自身的近期请求记录：尝试了什么、是否失败、停止原因、耗时和费用。用于诊断在 Browserless 端失败的运行。可查询时间范围取决于套餐。

原生文件暂存（默认禁用）

完整 HTTP 接口提供 browserless_stage_file，使用原生的 openai/fileParams 文件描述符。它不属于 stdio 和合规接口。**原生下载目前已禁用：**生产环境主机名允许列表为空，因此每个暂存请求都会在 DNS 或网络访问前失败。工具输入和环境变量无法启用此功能。

实现接受 file.download_url 和 file.file_id，并可选接受 file.mime_type 和 file.file_name。在代码中验证并启用可信主机后，成功暂存只会返回 { handle, filename, mimeType, size }。 将该句柄传给 browserless_agent 的 uploadFile；句柄归经身份验证的令牌所有，可重复使用 15 分钟，且不绑定到任何 MCP 传输方式。除非上传时提供覆盖值，否则会沿用存储的 MIME 类型。

受控测试无法证明原生 ChatGPT 附件能否被接受。实际附件的接受情况，以及句柄能否在已部署的副本之间解析，仍未经验证；文件存储是进程本地的。现有 multipart /upload 和内联内容上传不受影响。

Skills

此服务内置了一个 Skills 库，其中包含可按需加载的操作指南，帮助 Agent 处理棘手的页面交互机制。当触发条件满足时（例如 Agent 遇到 Cookie 横幅），Skills 会自动注入 browserless_agent 的响应中；也可以通过 browserless_skill 工具手动加载。

Skill	来源	用途
shadow-dom	src/skills/shadow-dom.md	通过 shadow root 使用深层选择器并定位 iframe。
cookie-consent	src/skills/cookie-consent.md	针对特定供应商的关闭指南（OneTrust、Cookiebot、Didomi、TrustArc 等）。
modals	src/skills/modals.md	关闭对话框、警报对话框，以及覆盖层关闭按钮的启发式方法。
captchas	src/skills/captchas.md	使用 solve 命令、响应语义和升级路径（仅限 Cloud）。
profile-import	src/skills/profile-import.md	使用 Browserless CLI 将用户本地 Chrome/Brave/Edge 登录信息作为个人资料导入（需征得同意，仅限完整接口）。
dynamic-content	src/skills/dynamic-content.md	为异步/AJAX/SPA 内容选择合适的 wait* 方法。
snapshot-misses	src/skills/snapshot-misses.md	处理截断或为空的快照，以及以图像形式呈现的内容。
screenshots	src/skills/screenshots.md	何时使用屏幕截图而非快照，以及范围和格式的选择。
tabs	src/skills/tabs.md	多标签页工作流，以及通过 targetId 偷看而不切换标签页。

显式加载 Skill：

{
  "method": "tools/call",
  "params": {
    "name": "browserless_skill",
    "arguments": { "id": "cookie-consent" },
  },
}

内置代理（browserless_agent）

在 browserless_agent 上传递顶层 proxy 对象，即可通过数据中心或住宅 IP 路由会话。数据中心代理的每 MB 成本较低；住宅代理较不容易被拦截。

{
  "method": "tools/call",
  "params": {
    "name": "browserless_agent",
    "arguments": {
      "method": "goto",
      "params": { "url": "https://example.com" },
      "proxy": {
        "proxy": "residential",
        "proxyCountry": "us",
        "proxySticky": true,
      },
    },
  },
}

字段	说明
proxy	"datacenter" 表示成本较低；如果目标网站会拦截数据中心流量，则使用 "residential"。
proxyCountry	ISO-2 国家代码（"us"、"de"）。会自动转换为小写。非字母值将被拒绝。
proxyState	美国州名，空格替换为下划线（"new_york"）。仅限付费计划使用；不符合条件的令牌会收到 401。
proxyCity	城市目标。仅限付费或企业计划使用；不符合条件的令牌会收到 401。
proxySticky	底层 WebSocket 保持打开期间使用稳定的 IP。重新连接（空闲断开、网络短暂中断、浏览器崩溃）时，会分配新的粘性 ID 和新 IP。
proxyLocaleMatch	将 navigator 区域设置与代理 IP 所属国家/地区匹配。
proxyPreset	仅限住宅代理使用的命名预设（例如 "px_amazon01"）。可用预设取决于计划；请向 Browserless 支持团队询问可用列表。
externalProxyServer	使用自有上游代理，例如 http://user:pass@host:port。必须使用 http:// 或 https://。

注意： 地理位置、粘性和区域设置选项需要使用内置的 proxy 级别或 externalProxyServer；proxyPreset 则需要 proxy: "residential"。MCP 会拒绝不受支持的组合，而不是让 API 静默忽略这些组合。

会话创建时只读取一次 proxy 对象。如需更改，请调用 close 并启动新会话——Agent 客户端根据代理指纹为会话编制键，因此传入不同的配置会连接到新的 WebSocket。

OS 角色（browserless_agent）

Agent 会话可以通过顶层创建选项选择一套协调一致的 OS 角色：

字段	说明
emulationOs	"windows"、"macos"、"linux" 或 "android"。启用平台伪装。
emulatedDevice	Android 设备标识；仅与 emulationOs: "android" 搭配使用。
screen	桌面屏幕，格式为 WIDTHxHEIGHT。
deviceScaleFactor	桌面设备像素比：1 或 1.25。
deviceSlot	非负的稳定桌面设备插槽；服务端会验证账户对应的有效范围。

在首次调用时、导航之前设置角色选项，之后复用返回的 sessionId。浏览器会话的整个生命周期内角色保持不变； 如需选择其他角色，请先关闭当前会话。

配置

该服务托管于 https://mcp.browserless.io/mcp。可通过请求头（推荐）或 ?token= 查询参数进行身份验证。

通过 AI Agent 安装？请参阅 install.md，获取 Agent 可读的设置说明。

使用请求头（推荐用于支持请求头的客户端）：

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

使用 URL 查询参数（适用于 Claude.ai 自定义连接器等仅接受 URL 的客户端）：

https://mcp.browserless.io/mcp?token=your-token-here

若要连接到特定的 Browserless 区域端点，请添加 x-browserless-api-url 请求头或 browserlessUrl 查询参数：

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here",
        "x-browserless-api-url": "https://production-lon.browserless.io"
      }
    }
  }
}

https://mcp.browserless.io/mcp?token=your-token-here&browserlessUrl=https://production-lon.browserless.io

如果同时提供请求头和查询参数，则优先使用请求头。

API URL 覆盖仅限于 browserless.io、其子域名、已配置的 BROWSERLESS_API_URL 源（协议、主机名和端口相同），以及 MCP_ALLOWED_API_URL_HOSTS 中列出的主机。允许使用路径，但不允许包含凭据、查询字符串和片段（包括单独的 ? 或 #）。如果未指定覆盖项，则按原样使用由操作方配置的 URL。

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

Cursor

添加到你的 Cursor MCP 设置：

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

VS Code

添加到你的 VS Code 设置（settings.json）：

{
  "mcp": {
    "servers": {
      "browserless": {
        "url": "https://mcp.browserless.io/mcp",
        "headers": {
          "Authorization": "Bearer your-token-here"
        }
      }
    }
  }
}

Windsurf

添加到你的 Windsurf MCP 配置：

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

自托管

也可以在本地运行该服务，适用于气隙部署或连接到自托管的 Browserless 实例。克隆此仓库并构建 Docker 镜像：

docker build -f docker/Dockerfile -t browserless-mcp .

docker run \
  -e BROWSERLESS_TOKEN=your-token \
  -e BROWSERLESS_API_URL=https://your-browserless-instance.example.com \
  -p 8080:8080 \
  browserless-mcp

然后使用与上述相同的请求头／查询参数身份验证方式，将 MCP 客户端指向 http://localhost:8080/mcp。

自托管环境变量

变量	必需	默认值	描述
BROWSERLESS_TOKEN	是	—	你的 Browserless API 令牌
BROWSERLESS_API_URL	否	https://production-sfo.browserless.io	API 端点（用于可自托管的 Browserless）
MCP_ALLOWED_API_URL_HOSTS	否	—	允许客户端提供的 API URL 覆盖值使用的主机，以逗号分隔；此外还允许 Browserless 和已配置的 API 来源
BROWSERLESS_API_SERVER	否	https://api.browserless.io	账户 API 主机——为 browserless_account、_usage、_sessions 和 _logs 提供支持。与 BROWSERLESS_API_URL 不同，后者是浏览器运行时。请谨慎配置：重放下载会获取此 API 返回的签名链接，因此只能将其指向你运营的端点
TRANSPORT	否	stdio	传输类型：stdio 或 httpStream
PORT	否	8080	HTTP 服务端口（仅用于 httpStream 传输）
BROWSERLESS_TIMEOUT	否	30000	请求超时时间，单位为毫秒
BROWSERLESS_MAX_RETRIES	否	3	失败请求的最大重试次数
BROWSERLESS_CACHE_TTL	否	60000	缓存 TTL，单位为毫秒（设为 0 可禁用）
AMPLITUDE_API_KEY	否	—	Amplitude 项目 API 密钥。用于发送 MCP 使用情况分析数据——包括 SDK 生命周期事件，以及我们自己的工具/技能事件
MCP_COMPLIANCE_MODE	否	未设置（完整功能集）	提供符合目录规范的精简功能集。默认关闭：任何已设置的值（false/0/no/off 除外）都会启用此模式

托管式 OpenTelemetry

对于 httpStream，将 OTEL_ENABLED=true 和 OTEL_EXPORTER_OTLP_ENDPOINT 设置为受信任收集器的基础 URL。指标和 stderr 日志通过 OTLP HTTP/protobuf 导出；追踪已禁用。stdio 不会启动此 SDK。 OTEL_METRIC_EXPORT_INTERVAL 用于控制导出间隔，单位为毫秒 （默认值为 60000，最小值为 1000）。

NodeSDK 管理各个提供程序，标准 Node 运行时检测会发出 nodejs.* 和 v8js.* 指标。应用的会话、工具、账户和 Redis 指标仍归属 browserless.mcp.*。所有时长指标的单位均为秒 （s），内存单位为字节（By），请求计数器使用 {request}； 应用调用方仍提供 毫秒，指标记录器会进行一次转换。

browserless.mcp.auth.duration 和 .auth.in_flight 统计 POST 身份验证， 而非整个请求的执行过程。browserless.mcp.session.cleanup.age 统计跟踪到的 MCP 空闲回收以及显式／空闲／上限触发的 Agent 清理，不统计每次会话关闭。 通过扫描发现的 MCP 时长从发现时开始计算；Agent 时长会在重新连接时重置。 browserless.mcp.accounts.active 统计每个采集窗口内不同的令牌哈希数量。热门账户计数以 INFO 日志记录，日志正文包含事件 browserless.mcp.account.window、active_accounts 和 top_accounts（最多 20 个 {hash, count} 条目），不会生成持久的逐账户指标序列。 空闲窗口不会生成账户日志。stderr 文本为 INFO，console.warn 为 WARN， 参数中包含 Error 时为 ERROR；stderr 记录带有 log.iostream=stderr。OTEL_SDK_DISABLED=true 也会禁用托管式遥测。

对于基于初始遥测 PR 构建的仪表板：将自定义事件循环 指标替换为 nodejs.eventloop.*，将 GC 暂停替换为 v8js.gc.duration，并将活动 资源替换为 v8js.resource.active。从工具／上游／Redis 时长名称中移除 _ms，使用上述身份验证和清理指标名称，并将毫秒 阈值除以 1000。将 account.requests 查询替换为窗口日志。 时长直方图的边界也以秒为单位，涵盖从亚秒级 Redis 操作到两小时会话的时长。Amplitude 事件字段和超时 配置仍以毫秒为单位。

技能检索诊断

每次实际远程技能获取都会通过现有分析队列发出一次 Skill Retrieval Completed（需配置 ANALYTICS_ENABLED、SQS_QUEUE_URL 和 SQS_REGION）。不会通过 SDK 的 AMPLITUDE_API_KEY 传输重复发送。缓存命中以及共享同一次获取的并发调用不会再次发出完成事件。获取失败后可在下次调用时重试；此检测不会增加重试。

字段包括 result=hit|miss|error、规范化后的 domain、UUID request_id、source、attempt、整数 duration_ms、stage=fetch|decode|validate，以及可用时的 http_status。skill_count 仅出现在有效响应中：命中时为正数，未命中时为零。错误包含 error_category=timeout|network_error|http_error|invalid_json|invalid_shape。来源包括 cli_agent、script_builder、autologin、agent_run、mcp_client 或 unknown。目前每次获取的 attempt=1；这些调用位置没有可用的运行标识符，因此省略 run_id。 不符合有界主机名格式的域会变为 invalid，但仍会计入完成事件的分母。

将 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 设置为受信任收集器的完整 /v1/logs URL，即可导出匹配的 skill.retrieval.failed WARN 记录，格式为 OTLP/HTTP JSON。默认情况下禁用导出。导出请求的截止时间为 1 秒，最多允许 16 个请求同时进行，且不重试。捕获到的队列或技能分析错误会生成 skill.telemetry.delivery_failed，包含 originating_event 和固定诊断类别 delivery_error，每个进程每分钟最多一次。导出器错误会被忽略，不会递归报告自身。 新增日志不会包含令牌、提示词、完整 URL、响应正文或配方文本。队列会保留现有的身份验证字段，并与日志字段分开。

失败属性示例：

{
  "event.name": "skill.retrieval.failed",
  "result": "error",
  "domain": "shop.example",
  "request_id": "416e0409-25e2-4399-a3fa-6939f43a75e0",
  "source": "mcp_client",
  "attempt": 1,
  "stage": "fetch",
  "error_category": "http_error",
  "http_status": 429,
  "duration_ms": 17
}

检索错误率 = 错误完成数 / 所有完成数。命中率 = 命中完成数 / 有效完成数。不要将单独的服务端 Skill Lookup 事件计入这两个分母。测试使用本地/模拟接收端；配置导出器或看到控制台消息都不能证明远程端已收到数据。

失败诊断

MCP Tool Request 保留 analytics_version=2、现有的粗粒度 error_category、status_code、计时信息和工具专属属性。这些新增诊断字段仅用于失败；成功重试时不会包含这些字段。

属性	含义
error_reason	selector_miss、invalid_params、unknown_method、script_error、unauthorized、forbidden、not_found、server_error、session_lost、navigation_failed、timeout、rate_limited 或 unknown。Agent 错误保留其现有的详细分类；本地 URL/批次验证错误为 invalid_params。
error_source	validation、script、target_website、api、transport 或 unknown。这用于标识观察到的故障边界，而非归责。仅凭 403 无法确定其来源。
failed_command_index	调用中命令批次内从 0 开始的索引，而非整个会话的命令计数器。若在命令启动前因设置/验证失败，则省略。
failed_method	失败命令中已识别的类型化方法名称。为避免输出任意输入，会省略无法识别的自由格式方法名称；索引仍可标识该命令。
error_code	允许列表中的结构化代码：上述大写原因名称、SELECTOR_NOT_FOUND、BROWSER_CRASHED、ECONNRESET、ECONNREFUSED、ENOTFOUND、EAI_AGAIN、ETIMEDOUT。不透明/无法识别的代码会被省略，不会复制到消息中。
error_status_code	结构化错误元数据中携带的整数 HTTP 状态码（100–599）。绝不会从错误文本中提取。
error_status_origin	对于观察到的 API 响应/升级，为 api；对于失败的导航结果，为 target_website；其他情况为 unknown。无结构化状态码时省略。
error_message	合成的摘要，最多 500 个字符。绝不会将原始错误消息、响应正文、HTML、脚本、选择器、凭据、Cookie、授权标头和 URL 复制到此字段中。
对于 browserless_function、browserless_export 和 browserless_smartscraper，
失败结果记录的 status_code 决定失败原因：函数工具返回 400 → script_error（来源为 script），401 → unauthorized，403 → forbidden，
404 → not_found，408 → timeout，429 → rate_limited，5xx → server_error，
其他情况 → unknown。函数和导出状态码是 Browserless API 的状态码（error_status_origin=api）；智能抓取器的状态码则是目标网站的状态码（error_status_origin=target_website、error_source=target_website）。导出工具的 400 仍归类为 unknown，但会保留其状态码。

status_code 保留其原有的工具特定含义；新增的状态字段不会取代它，也不会将成功的目标网页 HTTP 响应转为失败。即使 HTTP 失败是通过抛出异常产生的，也会保留 API 响应状态码。

如果结构化错误中已有状态码，或现有的 4xx 错误处理程序读取的 JSON 正文中包含状态码，则会保留该状态码；诊断逻辑不会在 5xx 失败时额外读取响应正文。

缺少结构化证据的搜索失败会报告 error_reason=unknown 和 error_message="Unclassified search failure."。为兼容图表，原有的 user_error 类别仍会保留，但它不代表调用方有过错。

示例分类：筛选 success=false，并按 tool → error_reason 分组；对于 Agent 调用，按 failed_method → error_reason 分组；对于 HTTP 失败，按 error_status_origin → error_status_code 分组。旧事件中缺少字段表示未提供相应的埋点信息，并不意味着失败原因是 unknown。不会回填历史数据。部署后，请验证收到的代表性事件，再将这些属性视为生产环境中可用的数据。

实时 URL 说明

browserless_live_url 通过 REST 为现有浏览器创建查看器链接。交接给人工处理时，请设置 action: "create"、browserId 和 interactable: true：

{
  "action": "create",
  "browserId": "running-browser-id",
  "interactable": true,
  "instructions": {
    "layout": "panel",
    "format": "markdown",
    "title": "Complete sign in",
    "summary": "Enter your **verification code**.",
    "steps": ["Open your inbox", "Enter the code"],
    "currentStep": 2
  },
  "doneLabel": "Continue",
  "failLabel": "Need help",
  "requesterName": "Support"
}

纯字符串说明仍然可用。使用字符串时，请在顶层设置 instructionsTitle、steps、currentStep 和 instructionsFormat。 使用对象时，请在 instructions 中设置这些值，分别作为 title、steps、currentStep 和 format。按钮标签和请求者姓名仍设在顶层。 标题最多 80 个字符；最多可设置 10 个非空步骤，每个步骤最多 300 个字符； 按钮标签最多 40 个字符；请求者姓名最多 60 个字符。 currentStep 从 1 开始，且必须对应已提供的步骤。服务器会去除摘要文本首尾空格，并将其限制为最多 2048 个字符。支持仅含步骤的卡片。Markdown 链接必须使用 HTTP 或 HTTPS。服务器会验证字段间的约束；部署环境必须支持富文本 REST 说明。

MCP 资源

资源 URI	描述
browserless://api-docs	智能抓取器 API 文档
browserless://status	实时服务健康状态

MCP 提示词

提示词	描述
scrape-url	抓取网页并总结其内容
extract-content	从网页中提取特定信息

开发

npm install
npm run build
npm test
npm run coverage

测试

测试套件使用 Mocha、Chai 和 Sinon。测试规格与代码一同存放在 test/（test/lib/、test/tools/、test/prompts/、test/resources/、test/integration/），并针对编译后的 build/ 输出运行。

• npm test — 编译 TypeScript，并运行 build/test/ 下的所有 *.spec.js。无需外部服务或 BROWSERLESS_TOKEN；API 客户端会被替身替代。
• npm run coverage — 使用 c8 运行测试套件，阈值在 package.json 中配置（行覆盖率 ≥ 80%，分支覆盖率 ≥ 70%，函数覆盖率 ≥ 80%）。

每次提交拉取请求时，都会在 Node 24 上通过 测试工作流 自动运行测试。合并前，PR 必须确保测试套件全部通过。

API 令牌

在 browserless.io 获取 API 令牌。该令牌用于验证所有发往 Browserless API 的请求。

许可证

SSPL-1.0