unbrowser by Unchained

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 或经过身份验证的任务。可通过 https://unchainedsky.com/unbrowser-mcp 使用共享的 Streamable HTTP MCP 端点进行公共冒烟测试；生产会话应使用本地安装。

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

选择合适的层级

当仅使用 HTTP 过于有限，而完整浏览器又成本过高时，使用 unbrowser。当页面需要 Chrome 时，输出会提示 Agent 升级处理，而不是假装具备它并不支持的兼容性。

快速开始

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 罐、GET 和 URL 编码的 POST 表单提交、链接和重定向都会在会话内保留。
• 页面和挑战信号：density.likely_js_filled、thin_shell 和 challenge.provider 会告知 Agent 是否应运行脚本、检查嵌入数据、停止，或升级到授权的浏览器会话。
• 每个结果都附带路由辅助信息：micro_hint（下一个具体步骤）、next_tools（按优先级排序的候选项）、avoid（没有可操作内容的工具），以及稳定的 escalation 分类（challenge、thin_shell、partial_result 等），包含可重试性／严重程度／证据——建议绝不会与 avoid 相矛盾。
• 结构化辅助工具：路由发现、卡片提取、表格规范化、text_main 和选择器调试，涵盖常见的提取工作流。

脚本模式和升级处理

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

启用 exec_scripts: true 后，内联和外部脚本会在带有超时保护的 QuickJS 中运行。这可以实现轻量级页面水合，并获取可见数据；但它不是 V8，也不是渲染引擎。较重的 React／Vue／Ember 应用仍可能只留下空壳。

当获准执行的任务需要真实像素、Canvas／WebGL、Workers、浏览器扩展、V8 兼容性、已认证的个人资料或人工确认时，请升级到 unchainedsky-cli 或 Unchained。如果用户已在 Chrome 中建立授权会话，cookies_set 可以在必要的会话 Cookie 过期前将其导入本地；这并不意味着可以规避网站的控制措施。

文档

许可证

Apache-2.0 —— 参见 LICENSE。