Browserbase

@mindstone/mcp-server-browserbase

通过 Browserbase API 实现云端浏览器自动化：会话支持实时视图调试、AI 网页 Agent、持久化上下文、下载、抓取/搜索和无服务器函数。

适用于需要本地浏览器自动化连接器、覆盖整个 Browserbase API 的 MCP 主机——从“打开浏览器给我看看”到“运行 Agent 提取定价数据”。

状态

• 版本： 0.1.1 · npm
• 身份验证： API 密钥（BROWSERBASE_API_KEY）
• 工具： 53（项目、会话、上下文、Agent、Agent 运行、下载、扩展、证书、抓取/搜索、函数）
• 接口： 云 API
• 机器可读： STATUS.json

项目缘由

Browserbase 的 API 涵盖从原始 CDP 会话到全托管 AI Agent 的各种功能。此软件包通过一个连接器，将所有功能提供给本地 stdio MCP 主机，并设置了明确的防护措施：在工具描述中注明会话计费，对破坏性操作添加标注，始终将外部网页内容包装为不可信数据，并轮询长时间运行的任务（Browserbase 不支持 Webhook）。

交互示例

“从 example.com 提取定价层级，并以 JSON 格式提供给我。”

主机调用的工具：

1. create_agent_run — 使用任务和用于定义 JSON 结构的 result_schema 启动一次运行。
2. wait_for_agent_run — 轮询直到运行完成，并返回结构化结果。
3. get_agent_run_messages —（可选）逐步查看 Agent 执行的操作。

响应（节选）：

{
  "ok": true,
  "runId": "r0a0b0c0-…",
  "status": "COMPLETED",
  "result": { "plans": [ { "name": "…", "price": 0 } ] },
  "waited_seconds": 47
}

要求

• Node.js 20+
• npm
• Browserbase API 密钥（browserbase.com/settings）。

一键安装

点击按钮后，主机将提示你填写：BROWSERBASE_API_KEY。

{
  "mcpServers": {
    "Browserbase": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-browserbase"
      ],
      "env": {
        "BROWSERBASE_API_KEY": ""
      }
    }
  }
}

快速开始

安装并构建

cd <path-to-repo>/connectors/browserbase
npm install
npm run build

npx

npx -y @mindstone/mcp-server-browserbase

本地运行

node dist/index.js

配置

在提供凭据桥接的宿主环境中运行时，configure_browserbase_api_key 会通过宿主持久保存密钥，而不是使用环境变量。

MCP 宿主配置

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-browserbase"],
      "env": {
        "BROWSERBASE_API_KEY": "your-api-key"
      }
    }
  }
}

安全说明

会话会产生费用 — 请及时释放

每次 create_session 都会启动一个按分钟计费的浏览器（最低计费 1 分钟）。create_session 和 end_session 的描述会明确告知 Agent 这一点；自动化完成后，应立即调用 end_session。超过项目并发限制时，会返回 429 错误，并附带 retry-after 时间窗口；错误解决信息会原样显示该窗口。

实时查看 URL 可授予控制权限

get_session 会返回经过凭据授权的 connectUrl，而 get_session_debug_urls 会返回调试器／实时查看 URL。任何拥有这些 URL 的人都可以查看并操控浏览器——这些 URL 仅用于与会话所有者分享，切勿公开。

外部内容始终经过封装

所有在你的帐户之外创建的内容——获取的页面内容、搜索结果、调试 URL 中的页面标题、Agent 运行任务／结果／消息、CDP 日志正文、回放播放列表、下载文件名、函数输出、错误详情——在传递给模型之前，都会封装在 <untrusted-content source="browserbase:…"> 中，并对结束标签进行转义，防止标签逃逸。CDP 日志的 rawBody 值超过约 4KB 时，还会被截断并附带截断说明。

文件上传受工作区沙箱限制

upload_session_file、upload_extension 和 upload_certificate 接受本地 file_path。读取操作使用规范路径前缀包含检查，限制在 MCP_WORKSPACE_PATH 指定的目录内（未设置时使用系统临时目录）：在读取磁盘前，会拒绝 .. 路径遍历、指向沙箱外部的绝对路径，以及逃逸出沙箱的符号链接。读取时先打开文件，再进行验证：连接器会打开文件描述符，确认打开的 inode 就是通过沙箱检查的文件，通过该描述符读取，然后在读取后再次检查——如果文件在读取过程中被替换或修改，操作会安全失败。

fetch_url 无法探测内部网络

fetch_url（以及你之后可能会获取的搜索结果中嵌入的 URL）受公开 URL 检查保护：只允许 http://／https:// 协议；在发送任何请求前，会拒绝 localhost、环回地址、链路本地和私有 IP 地址范围。

删除和停止工具已标注为破坏性操作

delete_context、delete_agent、delete_download、delete_extension、delete_certificate、end_session、stop_agent_run、invoke_function 以及所有 create_*／upload_* 工具都带有 destructiveHint: true。删除操作不可撤销；宿主应要求用户明确确认。

工具（53 个）

配置

• configure_browserbase_api_key — 保存 Browserbase API 密钥（存在桥接时由宿主持久保存）

项目

• list_projects — 列出项目（ID、并发限制、默认超时时间）
• get_project — 获取一个项目的详情
• get_project_usage — 查看已消耗的浏览器分钟数和代理字节数

会话

• create_session — 创建云浏览器会话（按分钟计费；返回 connectUrl）
• list_sessions — 列出会话，可按状态或 userMetadata 查询进行筛选
• get_session — 获取会话的状态和 connectUrl
• end_session — 释放会话（遵循 REQUEST_RELEASE 语义；会话也会自动过期）
• get_session_debug_urls — 获取可分享给他人的实时视图和调试器 URL
• get_session_logs — 获取 CDP 级别的会话日志（原始响应体超过约 4KB 时会截断）
• get_session_replays — 列出可供回放的录制页面
• get_session_replay_playlist — 获取页面的 m3u8 回放播放列表
• request_session_recording_downloads — 请求异步合成 MP4（HTTP 202）
• get_session_recording_downloads — 轮询 MP4 状态；获取短时有效的签名 URL
• upload_session_file — 将沙盒中的本地文件上传到会话内的 /tmp/.uploads/

上下文（持久化浏览器状态）

• create_context — 创建上下文，以便在多个会话间持久保存 Cookie/存储数据
• get_context — 获取上下文详情
• delete_context — 永久删除上下文

Agent

• create_agent — 创建可复用的 Agent（名称、系统提示词、结果架构）
• list_agents — 列出 Agent（游标分页，可按日期筛选）
• get_agent — 获取 Agent 的提示词和结果架构
• update_agent — 部分更新 Agent
• delete_agent — 删除 Agent（不影响已有运行）

Agent 运行

• create_agent_run — 启动运行（临时运行或使用 Agent；支持对敏感值进行 %variable% 替换）
• list_agent_runs — 列出运行（游标分页，可筛选）
• get_agent_run — 获取运行状态及终止结果/原因
• wait_for_agent_run — 推荐：轮询直至运行终止并返回结果
• get_agent_run_messages — 获取运行的 UIMessage 对话（since/nextSince 信息流）
• stop_agent_run — 停止正在运行的任务（202；若已终止则返回 409）

下载（在会话内下载的文件）

• list_downloads — 列出会话的下载内容（偏移量分页，可筛选）
• get_download_info — 获取元数据（大小、校验和、MIME 类型）
• get_download_file — 以 base64 格式获取字节数据（内联上限为 8MB）
• delete_download — 永久删除下载内容

扩展

• upload_extension — 上传打包为 zip 的 Chrome 扩展（沙盒文件读取）
• get_extension — 获取已上传的扩展
• delete_extension — 永久删除扩展

证书

• upload_certificate — 为 TLS 检查代理上传 CA 证书
• list_certificates — 列出已上传的证书
• get_certificate — 获取证书
• delete_certificate — 永久删除证书

抓取与搜索

• fetch_url — 服务端抓取：原始响应体、Markdown 或由架构定义的 JSON
• web_search — 网页搜索并返回排序后的结果

函数（无服务器浏览器自动化——仅支持列出/调用/检查）

• list_functions — 列出已部署的函数
• get_function — 获取函数
• invoke_function — 调用函数（异步 202；轮询调用状态）
• list_function_versions — 列出函数版本
• get_function_version — 获取版本的 userParamsSchema（调用前检查）
• list_function_invocations — 列出某个版本的调用记录
• get_function_invocation — 获取调用的状态、结果和原因
• get_function_invocation_logs — 获取调用日志
• list_function_builds — 列出函数构建
• get_function_build — 获取构建状态和失败原因
• get_function_build_logs — 获取构建日志

API 覆盖说明

• 上游已弃用：GET /sessions/{id}/recording（rrweb 事件转储）已被 Browserbase 弃用，并会返回弃用 404，因此此处有意不予提供。请改用 get_session_replays / get_session_replay_playlist（可观看），或录制下载工具（MP4 文件）。
• **无 Webhook：**Browserbase 采用轮询方式。Agent 运行（wait_for_agent_run / get_agent_run）、录制下载（get_session_recording_downloads）和函数调用（get_function_invocation）都通过轮询获取。
• 上下文或扩展没有列表端点——请记录创建时返回的 ID。
• 函数只能通过 Browserbase CLI 部署——此连接器可以列出、检查和调用现有函数，但无法创建函数。

错误处理

所有上游错误都会以结构化 JSON 返回，其中包含 ok: false、语义化 code（AUTH_REQUIRED、VALIDATION_FAILED、NOT_FOUND、CONFLICT、GONE、RATE_LIMITED、PAYMENT_REQUIRED、UPSTREAM_ERROR、TIMEOUT 等）以及可执行的 resolution。限流错误会包含服务器提供的 retry-after 时长。上游错误文本会封装为不可信内容，API 密钥绝不会出现在任何输出中。

许可证

FSL-1.1-MIT — Functional Source License，1.1 版，未来将采用 MIT 许可证。该软件将于 2030-04-08 转为 MIT 许可证。