unbrowser

面向 Agent 的低成本浏览器通行证。一个原生二进制。无需 Chrome。

官方 MCP 注册表标识： mcp-name: io.github.protostatis/unbrowser

unbrowser 是一个面向 Agent 的有状态、非可视化 Web 运行时。它介于 curl/WebFetch 与真实浏览器之间：保留 Cookie 和 DOM 状态，返回可查询的元素引用，处理链接和 HTML 表单，检测挑战与 SPA 信号，并且在静态 HTML 不够用时可以运行受限的 QuickJS 页面脚本。

**默认的 navigate 是一次快速的静态/SSR 遍历。**仅在需要受限 QuickJS 执行时才设置 exec_scripts: true。重型 SPA、像素、V8 保真度、扩展和交互式反机器人挑战属于真实 Chrome 层。

安装前先试试在线公共 Web 演示。它只接受页面上显示的固定公共源集合；请勿通过它发送私有数据、Cookie 或需要认证的任务。共享的 Streamable HTTP MCP 端点位于 https://unchainedsky.com/unbrowser-mcp，可用于公开冒烟测试；生产会话应使用本地安装。

仅在你有权访问的网站、账户和数据上使用 unbrowser。挑战检测和 Cookie 导入并不授予绕过访问控制或网站条款的权限。将会话 Cookie 视为凭据：将其保存在本地，限定于授权任务，并且切勿将它们发送到公共演示。

选择适合的层级

当仅靠 HTTP 过于笨拙、而完整浏览器又过于昂贵时，请使用 unbrowser。当页面需要 Chrome 时，输出会告诉 Agent 进行升级，而不是假装具备它并不拥有的兼容性。

Related MCP server: Browserbase MCP Server

快速开始

Docker — Linux amd64/arm64，约 13 MiB 拉取

docker pull ghcr.io/protostatis/unbrowser:latest

# One-shot navigation
docker run --rm ghcr.io/protostatis/unbrowser:latest \
  navigate https://example.com --json

# Default mode: MCP over stdio
docker run --rm -i ghcr.io/protostatis/unbrowser:latest

该镜像是 distroless 的，并以非 root 身份运行：没有 shell、包管理器或持久状态。在生产环境中请固定 :vX.Y.Z 或镜像摘要。

Python

pipx install pyunbrowser   # recommended on macOS / modern Linux
# or, inside a Python 3.10+ virtual environment:
pip install pyunbrowser

from unbrowser import Client

with Client() as ub:
    ub.navigate("https://news.ycombinator.com")
    for link in ub.query(".titleline > a")[:3]:
        print(link["text"], link["attrs"]["href"])

在 macOS 上，/usr/bin/python3 是 3.9，无法安装该 wheel；请使用 pipx 或 Homebrew Python。PyPI 发行包名为 pyunbrowser，而导入名和可执行文件仍为 unbrowser。

MCP

{
  "mcpServers": {
    "unbrowser": {
      "command": "unbrowser",
      "args": ["--mcp"]
    }
  }
}

最小化暴露面：添加 "--mcp-profile", "minimal" 只暴露 navigate/query/extract/help，并让 Agent 通过 help(topic) 发现其余工具。Python 封装器附带一个包含 3 个工具的智能服务器（search/open/help），作为 unbrowser-smart 控制台脚本提供。

{
  "mcpServers": {
    "unbrowser": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/protostatis/unbrowser:latest"
      ]
    }
  }
}

关于 Cargo、发布归档、源码构建、持久 shell 会话、原始 JSON-RPC 以及所有 MCP 选项，请参阅安装与接口参考。

Agent 获得什么

• navigate 返回一个 BlockMap：页面标题、地标、标题、交互元素、密度信号和 ASCII 大纲。其大小取决于页面；其结构用于规划，而非固定 token 的承诺。

• 稳定的元素引用（e:142）：一次查询元素后，即可直接 click、type 或 submit，无需重新解析 HTML。

• 有状态的 Cookie 与表单：Cookie jar、GET 和 URL 编码的 POST 表单提交、链接与重定向在会话内持续保持。

• 页面与挑战信号：density.likely_js_filled、thin_shell 和 challenge.provider 告诉 Agent 是运行脚本、检查内嵌数据、停止，还是升级到经授权的浏览器会话。

• 每个结果上的路由辅助：micro_hint（唯一的下一个具体步骤）、next_tools（排序后的候选工具）、avoid（无可操作对象的工具），以及稳定的 escalation 分类法（challenge、thin_shell、partial_result、…），带有 retryable/severity/evidence 字段——建议永远不会与 avoid 相矛盾。

• 结构化辅助工具：路由发现、卡片提取、表格规范化、text_main 和选择器调试覆盖常见的提取工作流。

脚本模式与升级

{"id":1,"method":"navigate","params":{"url":"https://example.com","exec_scripts":true}}

设置 exec_scripts: true 后，内联和外部脚本将在受限看门狗下于 QuickJS 中运行。这可以实现轻量水合，并显现可通过 fetch 获取的数据；它不是 V8，也不是渲染引擎。重量级的 React/Vue/Ember 应用仍可能留下一个空壳。

当一项被允许的任务需要真实像素、Canvas/WebGL、Workers、浏览器扩展、V8 兼容性、已认证的配置文件或人工确认时，请升级到 unchainedsky-cli 或 Unchained。如果用户已在 Chrome 中建立了经授权的会话，cookies_set 可以在本地导入所需的会话 Cookie，直至其过期；这不是绕过网站控制措施的许可。

文档

许可证

Apache-2.0 — 参见 LICENSE。