Cat Burglar

Cat Burglar

三种浏览器。一个 MCP。只关注变化。

Cat Burglar 为你的 Agent 接入真实浏览器。它可以运行经过补丁处理的隐身 Chromium、用于 DevTools 的原版 Chromium，或使用 Obscura 的 43 MB Rust 引擎，三者共用一个会话。它发送差异，而非完整 DOM 转储；会记住每个站点的工作流，并对高影响操作进行门控。出现 CAPTCHA 时，它会在浏览器窗口中打开页面并等待人工完成验证，然后继续操作。

你将获得

功能	重要性
三种引擎，一个服务	根据任务选择隐身、DevTools 保真度或 43 MB 的轻量引擎。切换引擎无需更换客户端。
差异，而非转储	稳定的引用、差异快照，以及每次操作后的有界变化观察。减少上下文占用和往返调用。
站点记忆	成功运行后学习并保存每个源的提示和工作流。重复任务所需步骤更少。
任意住宅代理	支持带身份验证的 HTTP、HTTPS 和 SOCKS5 代理池，支持粘性或轮换会话、地理位置匹配和按需运行状况检查。
远程 CDP 和云服务	可连接到 Browserbase、Steel、Browserless、Obscura Cloud，或本地已登录的 Chrome。无需本地浏览器进程。
按需深度 DevTools	仅在你提出请求时采集 HAR、CPU 配置文件、堆快照、覆盖率，以及网络/CPU 限速数据。
人工处理 CAPTCHA	Agent 会暂停，在浏览器窗口中打开页面并等待。你完成验证后，它会在同一会话中继续操作。
默认启用防护措施	SSRF 防护、源列表、不可信内容标记、跟踪器拦截，以及针对破坏性操作的确认门控。
兼容你的 Agent	支持 Claude Desktop、Claude Code、Cursor、Codex、Gemini CLI、VS Code、Windsurf、Cline、OpenCode、Docker 和任何 stdio 客户端。
经过测量	包含状态验证的 12 项本地测试套件。自适应观察在成功率不变的情况下，将文本量减少 29.9%，调用次数减少 15%。

支持范围

领域	功能
交互	点击、表单、输入、选择、上传、自由滚动、标签页、等待
读取	快照、差异、Markdown、链接、表格、JSON-LD、元数据、CSS 映射
DevTools	HAR、CPU 配置文件、堆快照、JS 覆盖率、网络/CPU 限速
隐身	Patchright、指纹自检、跟踪器拦截、WebRTC 泄漏标记、代理地理位置匹配
已登录和远程	持久化配置文件、存储状态、本地 Chrome CDP、Browserbase、Steel、Browserless
代理	HTTP、HTTPS、SOCKS5、身份验证、代理池、粘性/随机/轮询、运行状况和地理位置检查
记忆	每个源的提示和工作流，成功后学习，仅由 Agent 编写
安全	SSRF 防护、源列表、不可信标记、风险门控、审计日志
评测	12 项基准测试、完整与自适应模式对比、跨服务 LLM 运行器
OpenCode	Code Mode 命名空间、35 个工具、14 工具精简模式、服务说明

安装

一行命令：

curl -fsSL https://raw.githubusercontent.com/DrMkdaddy/cat-burglar/main/scripts/install.sh | bash

来自官方 MCP Registry：io.github.DrMkdaddy/cat-burglar（OCI 镜像）。
来自 GHCR：docker run -i --rm ghcr.io/drmkdaddy/cat-burglar:latest。

安装程序会将 cat-burglar 二进制文件添加到 PATH。如果你更喜欢使用 pnpm 全局安装：

pnpm add -g https://github.com/DrMkdaddy/cat-burglar/releases/download/v0.5.2/cat-burglar-mcp-0.5.2.tgz
cat-burglar doctor

install 命令会打印适用于以下客户端的即用型配置：claude-code、claude-desktop、cursor、codex、gemini、vscode、windsurf、cline、opencode 或 generic。

兼容

客户端	设置
Claude Code	claude mcp add catburglar -- cat-burglar
Claude Desktop、Cursor、Windsurf、Cline	粘贴 docs/install.md 中的 mcpServers JSON
Codex	codex mcp add catburglar -- cat-burglar
Gemini CLI	将 mcpServers 条目添加到 ~/.gemini/settings.json
VS Code	将 servers 条目添加到 .vscode/mcp.json
OpenCode	在 mcp.servers 下添加 catburglar
Docker	docker run -i --rm ghcr.io/drmkdaddy/cat-burglar:latest

请勿将服务命名为 browser。OpenCode 内置了同名的浏览器工具集，而 Code Mode 会隐藏重叠的工具。

将此提示词复制到你的 Agent 中

快速版本：

Install Cat Burglar from https://github.com/DrMkdaddy/cat-burglar as a local MCP server named catburglar.

Run:
curl -fsSL https://raw.githubusercontent.com/DrMkdaddy/cat-burglar/main/scripts/install.sh | bash

Then run `cat-burglar doctor`.

Add the server with command `cat-burglar` (add `--slim` if the client loads every tool schema), restart or reconnect the client, and verify by navigating to https://example.com and taking a snapshot. Report the tool count, engine, and page title.

包含客户端专属步骤、验证和安全规则的完整基础提示词：docs/agent-prompt.md。

<system_context>
You are installing Cat Burglar, a local browser MCP server, for this project.
</system_context>

<goal>
Add Cat Burglar to the current MCP client and verify that it can drive a browser.
</goal>

<install_steps>
1. Run:
   curl -fsSL https://raw.githubusercontent.com/DrMkdaddy/cat-burglar/main/scripts/install.sh | bash
   Then run `cat-burglar doctor` and report the output.
2. Add a local stdio MCP server named `catburglar` that runs `cat-burglar`.
   If the client loads every tool schema into context, add `--slim`.
3. Do not use the name `browser`. It collides with OpenCode's built-in browser tools.
4. Enable `BROWSER_MCP_ALLOW_PRIVATE_NETWORK=1` only if the user needs localhost.
5. Restart or reconnect the MCP client.
6. Verify with `navigate` to https://example.com, then `snapshot`, then `close`.
</install_steps>

<verification>
Report the server name, the tool count, the engine, and the title returned by the test page.
</verification>

<constraints>
Do not commit secrets. Do not enable private-network access without asking. Use the measured
12-task local numbers if numbers are needed. Do not invent a head-to-head result.
</constraints>

<user_prompt>
Install and verify Cat Burglar for my agent.
</user_prompt>

示例提示词

研究：

Use catburglar. Open https://news.ycombinator.com, take a snapshot, read the top five stories with markdown, and give me the titles and links.

表单和工作流：

Use catburglar. Open the staging signup page, fill the form with test data, submit it, and tell me exactly what changed on the page.

本地应用测试：

Use catburglar with engine chromium. Open http://localhost:3000, log in with the seeded test user, open the billing page, capture a screenshot, and report console errors.

性能：

Use catburglar with engine chromium. Open the product page, start a performance trace, reload, stop the trace, and summarize the long tasks and the three slowest scripts.

三种浏览器

引擎	最适合	占用空间
patchright	受保护的网站、登录、反机器人操作	完整 Chromium
chromium	Devtools、控制台、跟踪、PDF、本地应用测试	完整 Chromium
obscura	大批量读取和低内存场景	约 43 MB

{ "engine": "obscura", "restart": true }

运行中的浏览器无法直接切换引擎。调用 open 并设置 restart: true。

远程 CDP 和云浏览器

连接到任意 Chrome DevTools Protocol 端点，而不是启动本地浏览器：

{
  "engine": "remote",
  "cdp_url": "wss://connect.browserbase.com?apiKey=YOUR_KEY"
}

这适用于 Browserbase、Steel、Browserless、Obscura Cloud 或任何其他 CDP 提供商。对于已登录的本地 Chrome，请使用单独的配置文件启动：

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/cat-burglar-chrome

然后调用 open({ "engine": "remote", "cdp_url": "http://127.0.0.1:9222" })。不会重复启动本地浏览器进程，因此此方式不会额外占用浏览器内存。

住宅代理

Cat Burglar 支持任何 HTTP、HTTPS 或 SOCKS5 代理，无论是否需要身份验证。代理池可以轮换、保持粘性，或按会话选择。

{
  "proxyPool": [
    { "id": "us-1", "url": "http://user:[email protected]:8000", "geo": { "timezone": "America/New_York", "locale": "en-US" } },
    { "id": "de-1", "url": "socks5://user:[email protected]:1080", "geo": { "timezone": "Europe/Berlin", "locale": "de-DE" } }
  ],
  "proxyOptions": {
    "mode": "sticky",
    "matchGeo": true,
    "testOnLaunch": false,
    "rotateOnError": true
  }
}

你也可以传入 host:port:user:pass，Cat Burglar 会对其进行规范化。使用代理工具检查、测试、轮换、添加或移除条目：

{ "action": "test", "force": true }
{ "action": "rotate" }
{ "action": "add", "url": "http://user:[email protected]:8000", "label": "us-residential" }

代理 URL 在输出和审计日志中会被隐藏。启用代理后，Chromium 会使用 WebRTC 泄漏防护标志，而 matchGeo 会使浏览器时区和区域设置与代理出口保持一致。健康检查按需通过 curl 运行，因此不会增加浏览器进程。

操作循环

1. 使用 navigate 打开页面。
2. 使用 snapshot 获取 URL、标题、控件和稳定引用。
3. 按引用执行 click、fill 或 select。
4. 阅读操作返回的变更观察结果。
5. 使用 markdown 阅读内容，使用 extract 获取结构化数据，使用 perf 查看跟踪信息。
6. 在成功完成可重复的工作流后，运行 memory learn。

只要元素仍在 DOM 中，引用就会保持有效。如果元素离开页面，操作会因引用过期而报错，而不会点击克隆元素。

按需使用 DevTools

devtools 工具仅在操作运行期间捕获 Chrome 内部信息。后台不会记录任何内容。

操作	结果
har_start / har_stop	HAR 1.2 文件，包含请求和响应元数据，可选包含请求与响应正文
cpu_start / cpu_stop	.cpuprofile 文件及最耗时的函数
heap	.heapsnapshot 文件
coverage_start / coverage_stop	按 URL 列出的未使用 JavaScript
throttle	网络延迟、带宽、离线模式和 CPU 限流

{ "action": "cpu_start" }
{ "action": "cpu_stop" }

CAPTCHA 转交

captcha 工具可检测 reCAPTCHA、hCaptcha、Turnstile、DataDome、PerimeterX、Arkose 和常见文本挑战，但不会解决挑战。

出现挑战时，请调用：

{ "action": "handoff" }

在本地桌面上，Cat Burglar 会以有头模式重新启动同一配置文件，返回当前页面并打开一个真实的浏览器窗口。你可直接在该窗口中解决挑战，然后调用 captcha 并设置 action: "wait"，Agent 便会在同一会话中继续操作。切换过程中，Cookie、存储和当前 URL 都会保留。

navigate https://accounts.hcaptcha.com/demo
  captcha: hcaptcha

captcha action=handoff
  mode: window
  url: https://accounts.hcaptcha.com/demo

[a real Chromium window opens on that page]

# you solve the widget

captcha action=wait
  detected: false

snapshot
  [e4] button "Submit"

服务端没有集成求解器。它会轮询页面，直到挑战消失。

如果没有显示器，或者引擎为 Obscura，handoff 会回退到环回实时查看页面。使用以下命令强制启用此回退：

{ "action": "stream", "open_window": false, "timeout_ms": 300000 }

对于远程 CDP 提供方，打开时请传入提供方的实时查看 URL：

{
  "engine": "remote",
  "cdp_url": "wss://connect.browserbase.com?apiKey=YOUR_KEY",
  "live_view_url": "https://browserbase.com/sessions/YOUR_SESSION"
}

captcha handoff 会返回该 URL，而不是打开本地窗口。流式转交受令牌保护，且仅绑定到 127.0.0.1；完成、超时或执行 close 时会停止。

基准测试

模式	成功数	工具调用次数	观察字符数	耗时
完整快照	12/12	80	30,029	15.37 s
差异 + 变更观察	12/12	68	21,057	13.86 s

在包含服务端状态检查的 12 项本地测试套件中测得。配置文件为 flash，引擎为 chromium，Node 版本为 26。原始 JSON：bench/results/2026-11-09-flash.json。

pnpm bench
pnpm bench:compare

工具

默认提供 35 个工具。--slim 模式下提供 14 个。

分组	工具
生命周期	open、close、navigate、back、forward、reload、status、tabs
读取	snapshot、markdown、extract、evaluate、screenshot、pdf
交互	click、fill、type、press、select、hover、scroll、upload、wait、captcha
状态	cookies、storage、stealth、memory、proxy
诊断	network、console、perf、devtools、resources、audit

extract 支持提取链接、表格、JSON-LD、meta 标签、文本和 CSS 字段映射。perf 支持 Web Vitals、CDP 指标、慢速资源和完整 Chrome 跟踪记录。

安全

• 导航和每个请求都受到 SSRF 防护，并进行 DNS 检查且覆盖重定向。
• 默认阻止私有、环回、链路本地、CGNAT、组播和保留地址范围，除非明确允许。
• 即使启用了私有网络访问，云元数据端点仍会被阻止。
• 提供带通配符主机的来源允许列表和阻止列表。
• 从页面提取的输出带有不可信内容标记。
• 删除、付款、转账、发送、发布和停用等高影响目标会被标记。设置 BROWSER_MCP_RISKY_ACTION_POLICY=ask 可要求明确确认。
• 站点记忆仅由 Agent 撰写。绝不摄取页面文本，会丢弃引用，并将输入值替换为占位符。
• 跟踪器拦截使用 Obscura 的 3,520 个域名 PGL 列表以及常见分析主机。

请将这些措施作为纵深防御体系中的多层防护。对于敏感账户，请使用 ask 策略，并在批准前检查确认内容。

资源效率

默认使用完整 Chromium，以确保保真度。除非收到请求，服务不会叠加运行多个浏览器、在后台录制或检查代理。

选项	内存影响
obscura 引擎	约 43 MB，而 Chromium 约为 1 GB
remote 引擎	不启动本地浏览器进程；使用远程 CDP 提供方
--slim	提供 14 个工具，而不是 35 个；降低架构开销
按需使用 DevTools	仅在执行相应操作期间运行 HAR、CPU、堆和覆盖率分析
代理测试	仅使用 curl，不启动浏览器进程
idleTimeoutMs	设置后，浏览器会在闲置时关闭
Flash 配置文件	快照、Markdown 和变更观察内容更精简

使用 resources 工具查看进程树 RSS、进程数、打开的页面和缓冲区大小。启动时会禁用后台联网、组件更新、同步、ping 和指标收集。

研究

设计基于对 2023 至 2026 年 Web Agent 相关工作的审阅，涵盖评估错误、观察对齐、变更观察、记忆、规划和提示词注入。完整审阅包含 40 个来源：docs/research/2026-11-browser-agent-research.md。

LLM 测试框架可以对 ours、playwright、chrome-devtools 或 obscura 运行相同的 12 项任务：

pnpm bench:llm -- --server ours

开发

pnpm install
pnpm build
pnpm test
pnpm smoke
pnpm bench
pnpm bench:compare
node dist/index.js doctor
node dist/index.js install --client claude-desktop

配置文件：~/.config/browser-mcp/config.json。示例：cat-burglar.config.example.json。环境变量会覆盖配置文件中的设置。

致谢

来源	许可证	使用内容
Obscura	Apache-2.0	Ref-token 快照思路、Markdown 和提取语义、SSRF 防护策略、跟踪器列表数据
Playwright MCP	Apache-2.0	无障碍优先的快照、持久化配置文件、来源和文件策略
Chrome DevTools MCP	Apache-2.0	性能指标和跟踪、网络和控制台检查
Patchright	Apache-2.0	隐身 Playwright 驱动程序
browser-use	MIT	Agent 操作词汇和拟人化交互思路

跟踪器列表是唯一复制的数据资产。请参阅 NOTICE。

状态

版本 0.5.2。已在包含 12 项任务的本地套件上进行基准测试，仓库中提供原始 JSON。LLM 测试框架可以在四个服务上运行相同的任务。欢迎提交问题和反例。

许可证

MIT。请参阅 LICENSE。