sendblue-browser-mcp

sendblue-browser-use

面向 Agent 的独立调试浏览器。基于隐身补丁版 Chromium，提供轻量级 HTTP API、持久化命名会话、便捷的清理端点、可配置的自动截图，以及 CDP 连接能力，因此任何客户端（Playwright、Puppeteer、undetected-chromedriver、自定义脚本）都可以驱动它。

它作为独立进程运行，不绑定任何一个 Claude / Cursor / Codex 会话，因此多个 Agent 可以同时使用它、互相调试各自的工作流，并重复使用已登录的会话，而无需每次运行都重新进行身份验证。

为何创建此项目

需求	可获得的能力
不绑定单个 Agent	长期运行的 HTTP 守护进程。任何持有 bearer token 的工具都可以驱动它。
看起来不像自动化程序	通过 patchright 为 Chromium 打补丁：隐藏 navigator.webdriver，修补 CDP 检测向量，并使用真实的 Chromium 二进制文件（没有 Playwright 指纹）。可通过常见的 Cloudflare Turnstile 等低门槛检查；不适用于大规模对抗性抓取。
可重复使用的会话	持久化的命名配置文件。登录一次，之后每次调试运行都会重复使用 Cookie。
一键重置	POST /sessions/:name/purge 会清除 Cookie 和活动页面存储，但保留会话 ID，因此客户端代码仍可继续运行。
适合多 Agent 使用	每个会话都是独立的 BrowserContext（或独立的配置文件）。可并行运行 5 个以上的调试会话，且状态互不影响。
CDP 连接	对于非持久化会话，GET /sessions/:name/cdp-url 会返回共享浏览器 CDP URL，因此 Playwright / Puppeteer / 任何 CDP 客户端都可以通过 connect() 连接到调试浏览器。
自动收集证据	导航截图遵循 NAV_SCREENSHOT_POLICY（默认：仅无头模式）。可选 Playwright 跟踪记录。
通过 HTTP 控制	直接使用 curl 即可。无需 SDK。
部署自包含	在任意 Mac mini / EC2 / Codespace 上运行一次 docker compose up 即可。无需主机安装 Chromium。

快速开始（本地）

前置条件：PATH 中需有 Bun >=1.3 和 Node.js >=20。

git clone https://github.com/sendblue-api/sendblue-browser-use.git
cd sendblue-browser-use
bun install
bun --bun x patchright install chromium

cp .env.example .env
# generate and set the required token
TOKEN="$(openssl rand -hex 32)"
sed -i.bak "s/^BROWSER_USE_API_KEY=.*/BROWSER_USE_API_KEY=$TOKEN/" .env
rm .env.bak

bun run dev

然后在另一个终端中运行：

source .env
TOKEN="Authorization: Bearer $BROWSER_USE_API_KEY"

# 1. create a persistent session (log in here once, reuse it forever)
curl -s -X POST http://127.0.0.1:8787/sessions \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"qa","persistent":true}'

# 2. navigate
curl -s -X POST http://127.0.0.1:8787/sessions/qa/navigate \
  -H "$TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://trybloom.so/"}'

# 3. screenshot
curl -s http://127.0.0.1:8787/sessions/qa/screenshot?fullPage=true \
  -H "$TOKEN" -o /tmp/qa.png

# 4. wipe state without losing the session
curl -s -X POST http://127.0.0.1:8787/sessions/qa/purge -H "$TOKEN"

快速开始（Docker）

echo "BROWSER_USE_API_KEY=$(openssl rand -hex 32)" > .env
docker compose up -d

同一套 API，开放在 127.0.0.1:8787 上。数据持久化在 ./data/ 中。默认情况下，CDP 仅在容器内的回环接口上开放；要从主机连接 CDP，仅可在可信机器上取消 docker-compose.yml 中 CDP_BIND 和 127.0.0.1:9222:9222 端口映射的注释。

安装到你的 Agent 中

此仓库提供三种打包层，让任何 Agent 都可以通过一行配置驱动守护进程。

MCP（Claude Desktop、Codex、Cursor、Antigravity、Cline、Windsurf）

适用于跨 Agent 使用的方案。将 HTTP API 封装为 MCP 工具（health、create_session、navigate、screenshot、script、get_cdp_url、purge_session 等）。

{
  "mcpServers": {
    "sendblue-browser": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "BROWSER_USE_URL": "http://127.0.0.1:8787",
        "BROWSER_USE_API_KEY": "<same token you start the daemon with>"
      }
    }
  }
}

添加到 ~/.cursor/mcp.json、~/Library/Application Support/Claude/claude_desktop_config.json、~/.gemini/config/mcp_config.json 等配置文件中。Codex 的配置如下：

codex mcp add sendblue-browser \
  --env BROWSER_USE_URL=http://127.0.0.1:8787 \
  --env BROWSER_USE_API_KEY=<daemon-token> \
  -- npx -y [email protected]

封装器源代码：mcp/。

Claude Code 插件

/plugin install sendblue-api/sendblue-browser-use

从此仓库拉取 .claude-plugin/plugin.json 和 skills/sendblue-browser/SKILL.md。

Codex / Antigravity / Cline 技能

同一个 skills/sendblue-browser/SKILL.md 可用作 Codex、Google Antigravity 和 Cline 的技能。将该文件夹复制到：

Agent	路径
Codex	~/.codex/skills/sendblue-browser/
Antigravity	~/.gemini/skills/sendblue-browser/
Cline	在 Settings 中启用 Skills，然后放入其 skills 目录

AGENTS.md 仓库

如果你的仓库已遵循 agents.md 约定，此仓库中的 AGENTS.md 也可作为可直接复制粘贴的内容，供任何希望调用此守护进程的使用方仓库使用。

API

除 /health 外，所有路由都需要 Authorization: Bearer $BROWSER_USE_API_KEY。

方法	路径	请求体 / 查询参数	返回值
GET	/health	—	{ ok, service, version, sessions, defaultHeadless, navScreenshotPolicy }
GET	/sessions	—	{ sessions: [...] }
POST	/sessions	{ name, persistent?, headless?, viewport?, userAgent?, locale?, timezone?, traces?, proxy? }	{ session }
GET	/sessions/:name	—	会话信息 + 当前页面的 url/title
POST	/sessions/:name/purge	—	{ session } — 清除 Cookie 和当前源的存储，保留会话 ID
DELETE	/sessions/:name	—	{ ok } — 关闭上下文并移除配置文件
POST	/sessions/:name/navigate	{ url, waitUntil?, timeoutMs? }	{ url, title, status }
GET	/sessions/:name/screenshot	?fullPage=true&selector=...	image/png
POST	/sessions/:name/script	{ code, timeoutMs? }（≤200kB）	{ result } — 代码在页面上下文中运行
GET	/sessions/:name/cookies	?url=...	{ cookies }
POST	/sessions/:name/cookies	{ cookies: [...] }	{ ok }
GET	/sessions/:name/console	?limit=100	{ messages: [...] }（环形缓冲区）
GET	/sessions/:name/cdp-url	—	{ cdpUrl, targetId } — 仅适用于非持久化会话

POST /sessions/:name/script 会将 code 直接传递给 Playwright 的 page.evaluate。发送 JavaScript 表达式，或将语句包装在 IIFE 中。脚本默认在 30s 后超时；可传入 timeoutMs，设置最长 120000，或设为 0 以禁用请求超时。

{ "code": "(() => { const x = 1; return x; })()" }

错误

所有非 2xx 响应都采用相同的封装格式。Playwright 的错误会在返回前截断为一行；完整消息会在服务端记录，并对代理凭据进行脱敏。

{ "error": { "code": "navigate_failed", "message": "net::ERR_NAME_NOT_RESOLVED" } }

状态码	代码	含义
400	empty_body	请求体为必填项，但未提供
400	malformed_json	请求体不是有效的 JSON
400	invalid_body	请求体未通过 Zod 验证（参见 error.details）
401	unauthorized	Bearer 令牌缺失或错误
404	not_found	会话不存在
409	already_exists	已有同名会话在运行
409	cdp_unavailable_for_persistent_session	持久化会话不会公开共享的 CDP URL
422	script_failed	/script 请求有效，但页面内的 eval 抛出异常或超时
500	internal_error	意外错误——请检查服务端日志
502	navigate_failed screenshot_failed cookie_read_failed cookie_write_failed session_unreachable	Chromium 端故障

会话选项

{
  name: string;            // required, [a-z0-9_-]
  persistent?: boolean;    // default true — profile data survives restarts
  headless?: boolean | "new"; // persistent sessions only; non-persistent uses DEFAULT_HEADLESS
  viewport?: { width, height };
  userAgent?: string;
  locale?: string;         // default "en-US"
  timezone?: string;
  traces?: boolean;        // capture a Playwright trace.zip on session close
  proxy?: { server, username?, password?, bypass? };
}

Cookie 格式

POST /sessions/:name/cookies 最多接受 500 个 Playwright 风格的 Cookie：

{
  cookies: Array<{
    name: string;
    value: string;
    url?: string;       // absolute URL, or domain + path
    domain?: string;
    path?: string;
    expires?: number;
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: "Strict" | "Lax" | "None";
  }>;
}

每个 Cookie 都必须包含 url，或同时包含 domain 和 path。

持久化与非持久化

• persistent: true（默认） — Cookie、localStorage 和 IndexedDB 会持久保存在 ~/.sendblue-browser-use/profiles/<name>/ 下。守护进程重启后，重新创建同名持久化会话即可复用该配置文件。无法通过 CDP 连接这些会话，因为每个会话都会获得独立的私有浏览器实例。
• persistent: false — 通过全新的 BrowserContext 共享中央 Chromium 进程。状态仅保存在内存中。可以通过 CDP 连接，使用 /sessions/:name/cdp-url 获取共享的浏览器级 CDP 端点以及会话页面对应的 targetId。CDP 客户端可以看到共享的调试浏览器，因此请确保 CDP 端口仅在本地开放且可信，并在操作前选择返回的目标。

对于“登录一次，调试一周”这类工作流，请选择持久化会话。需要直接连接 Playwright / Puppeteer 时，请选择非持久化会话。

示例

• examples/attach-from-playwright.ts — 通过 CDP 连接 Playwright 并操控页面（按照文件头部的说明使用 Node/tsx 运行）
• examples/attach-from-puppeteer.ts — 使用 Puppeteer 执行相同操作
• examples/multi-agent-debug.ts — 两个 Agent 并行操控两个界面
• examples/run-script.sh — 仅使用 curl 的操作指南

隐身说明

本项目基于 patchright 构建。它是一个持续维护的 Playwright 分支，能够：

• 隐藏 navigator.webdriver
• 移除 CDP 运行时标记
• 去除 Playwright 专用扩展和命令行标志
• 使用真实的 Chromium，因此大多数指纹特征都与普通用户相符

我们有意默认不传递 --disable-blink-features=AutomationControlled，也不覆盖 userAgent/viewport——patchright 会在内部处理这些设置，而我们的覆盖会破坏它的 rebrowser 补丁。只有在确有需要时，才为每个会话传入显式的 userAgent。

选择 patchright 而非其他方案的原因：

• 相较于 nodriver / undetected-playwright——patchright 维护活跃，与 Playwright 的 API 保持一致，并能与现有 TypeScript 生态系统顺畅集成。
• 相较于 Camoufox——Camoufox 使用 Firefox，并进行更深入的指纹随机化，更适合大规模对抗性抓取。patchright 则更适合在没有额外维护负担的情况下测试自有身份验证流程（Clerk、Stripe、Google OAuth、Cloudflare Turnstile）。

存储

~/.sendblue-browser-use/
├── profiles/
│   └── <session>/          # persistent profile dir
└── runs/
    └── <session>/
        ├── 2026-05-25T...-nav.png   # automatic nav screenshot when policy enables it
        └── 2026-05-25T...-trace.zip # if traces:true at create

POST /sessions/:name/purge 会清除整个上下文中的 Cookie 和权限，然后清除当前打开页面/来源的 localStorage、sessionStorage、IndexedDB、ServiceWorker 注册、CacheStorage 和控制台缓冲区。它不会枚举持久配置文件中所有历史来源，不会删除磁盘上的配置文件（因此会话 ID 仍然有效），也不会清除浏览器级 HTTP 缓存或 HSTS 状态。如需同时清除配置文件，请执行 DELETE /sessions/:name，然后重新创建。

自动导航截图遵循 NAV_SCREENSHOT_POLICY：

• headless（默认）：仅有效无头会话会生成 *-nav.png，避免有头浏览器出现可见的捕获闪烁。
• always：保留旧有行为，每次导航都会截图，包括有头会话。
• off：禁用自动导航截图。

每个会话的自动截图数量上限为 MAX_NAV_SCREENSHOTS（默认 200 张，优先删除最早的截图）。设置 MAX_NAV_SCREENSHOTS=0 可完全禁用自动截图。需要获取有头浏览器的证据时，请显式调用 /screenshot。

安全

• HTTP API 默认绑定到 127.0.0.1。设置 BIND=0.0.0.0 会使服务暴露在局域网中——这样做之前，请在前面配置带身份验证的反向代理。Docker 镜像会设置 BIND=0.0.0.0，以便主机端口发布正常工作，但 docker-compose.yml 仅发布到 127.0.0.1。如果直接运行 docker run -p 8787:8787，即表示你选择暴露 HTTP API。
• CDP 绑定到 CDP_BIND（默认 127.0.0.1；Docker 镜像默认也仅绑定到回环地址）。默认的 docker-compose.yml 不会发布 CDP；如果选择启用主机 CDP 附加，只能将其发布到 127.0.0.1。任何能够访问此端口的人都能在浏览器中执行任意代码（RCE）——请确保它仅绑定到回环地址。
• POST /sessions/:name/script 会在页面上下文中运行任意 JS。Bearer 令牌是唯一的访问限制。不要分享令牌。
• 请将 Bearer 令牌视为本地浏览器/网络控制凭证。持有令牌的人可以让 Chromium 导航到守护进程主机可访问的任意 http(s) URL，包括 localhost 和专用网络服务。
• POST /sessions/:name/navigate 仅接受 http(s) URL——file://、chrome:// 等都会被拒绝。
• 健康检查（GET /health）是公开的，因此 Docker/k8s 探针无需令牌即可工作；它仅返回服务元数据。

Architecture

HTTP :8787  ──►  Hono router  ──►  session manager  ──►  patchright Chromium
                                    │                    └─►  CDP :9222 (loopback; Docker opt-in)
                                    └─►  on-disk profiles + runs

Inspired by the Sendblue channel-server pattern (Bun + Hono + bearer auth + simple HTTP surface).

License

MIT. See LICENSE.