Skip to main content
Glama

browsegrab

한국어 문서 · llms.txt

专为本地 LLM 设计的 Token 高效浏览器代理 — Playwright + 辅助功能树 + MarkGrab,原生支持 MCP。

browsegrab 是一个轻量级浏览器自动化库,专为本地 LLM(8B-35B 参数)设计。它结合了 Playwright 的辅助功能树和 MarkGrab 的 HTML 转 Markdown 功能,与 browser-use 等替代方案相比,每步 Token 消耗减少了 5-8 倍。

特性

  • Token 高效:每步约 500-1,500 个 Token(相比 browser-use 的 4,000-10,000 个)

  • 本地 LLM 优先:针对 vLLM、Ollama 和兼容 OpenAI 的端点进行了优化

  • 原生支持 MCP:内置 MCP 服务器,包含 8 个浏览器自动化工具

  • 集成 MarkGrab:HTML → 简洁的 Markdown,用于内容提取

  • 辅助功能树 + 引用系统:稳定的元素引用(e1, e2, ...),无需视觉模型

  • 成功模式缓存:重复工作流无需调用 LLM

  • 5 阶段 JSON 解析器:针对本地 LLM 输出的稳健动作解析

  • 最小依赖:核心仅依赖 playwright + httpx

Related MCP server: BAP MCP

安装

pip install browsegrab
playwright install chromium

可选功能:

pip install browsegrab[mcp]      # MCP server support
pip install browsegrab[content]  # MarkGrab content extraction
pip install browsegrab[cli]      # CLI with rich output
pip install browsegrab[all]      # Everything

快速开始

Python API

from browsegrab import BrowseSession

async with BrowseSession() as session:
    # Navigate and get accessibility tree snapshot
    await session.navigate("https://example.com")
    snap = await session.snapshot()
    print(snap.tree_text)
    # - heading "Example Domain" [level=1]
    # - link "Learn more": [ref=e1]

    # Click using ref ID
    result = await session.click("e1")
    print(result.url)  # https://www.iana.org/help/example-domains

    # Type into search box
    await session.navigate("https://en.wikipedia.org")
    snap = await session.snapshot()
    await session.type("e4", "Python programming", submit=True)

    # Extract compressed content (AX tree + markdown)
    content = await session.extract_content()

CLI

# Accessibility tree snapshot
browsegrab snapshot https://example.com

# JSON output
browsegrab snapshot https://example.com -f json

# Extract content (AX tree + markdown)
browsegrab extract https://en.wikipedia.org/wiki/Python

# Agentic browse (requires LLM endpoint)
browsegrab browse https://example.com "Find the about page"

MCP 服务器

browsegrab-mcp  # Start MCP server (stdio)

Claude Desktop / Cursor / VS Code 配置:

{
  "mcpServers": {
    "browsegrab": {
      "command": "browsegrab-mcp"
    }
  }
}

8 个 MCP 工具:browser_navigate, browser_click, browser_type, browser_snapshot, browser_scroll, browser_extract_content, browser_go_back, browser_wait

工作原理

代理浏览循环

flowchart LR
    A["🌐 URL + Goal"] --> B["Navigate"]
    B --> C["AX Tree Snapshot\n~200–500 tokens"]
    C --> D{"LLM\nDecision"}
    D -->|"click / type / scroll"| E["Execute Action"]
    E --> C
    D -->|"goal reached"| F["Extract Content\n(MarkGrab)"]
    F --> G["✅ Result"]

Token 效率

browsegrab 将结构(辅助功能树)与内容(MarkGrab Markdown)分离,仅发送 LLM 所需的信息:

flowchart TD
    A["Raw HTML"] --> B["Accessibility Tree"]
    A --> C["MarkGrab Markdown"]
    B --> D["Structure: ~200–500 tokens\nInteractive elements with ref IDs"]
    C --> E["Content: ~300–800 tokens\nClean markdown · on-demand"]
    D --> F["Combined: ~500–1,300 tokens/step\n⚡ 5–8× fewer than browser-use"]
    E --> F

Token 效率(实测)

页面

交互元素

Token 数

browser-use 等效值

example.com

1

~60

~500+

维基百科文章

452

~1,254

~10,000+

架构

browsegrab/
├── config.py                 # Dataclass configs (env var loading)
├── result.py                 # Result types (ActionResult, BrowseResult, ...)
├── session.py                # BrowseSession orchestrator
├── browser/
│   ├── manager.py            # Playwright lifecycle (async context manager)
│   ├── snapshot.py           # Accessibility tree + ref system
│   ├── selectors.py          # 4-strategy selector resolver
│   └── actions.py            # navigate, click, type, scroll, go_back, wait
├── dom/
│   ├── ref_map.py            # ref ID ↔ element bidirectional mapping
│   └── compress.py           # AX tree + MarkGrab → compressed context
├── llm/
│   ├── base.py               # LLMProvider ABC
│   ├── provider.py           # vLLM, Ollama, OpenAI-compatible
│   ├── prompt.py             # System prompts (~400 tokens)
│   └── parse.py              # 5-stage JSON fallback parser
├── agent/
│   ├── history.py            # Sliding window history compression
│   ├── cache.py              # Domain-based success pattern cache
│   └── loop_guard.py         # Duplicate action detection
├── __main__.py               # CLI (click)
└── mcp_server.py             # FastMCP server (8 tools)

配置

所有设置均通过环境变量(BROWSEGRAB_* 前缀)进行:

# Browser
BROWSEGRAB_BROWSER_HEADLESS=true
BROWSEGRAB_BROWSER_TIMEOUT_MS=30000

# LLM (for agentic browse)
BROWSEGRAB_LLM_PROVIDER=vllm          # vllm | ollama | openai
BROWSEGRAB_LLM_BASE_URL=http://localhost:8000/v1
BROWSEGRAB_LLM_MODEL=Qwen/Qwen3.5-32B-AWQ

# Agent
BROWSEGRAB_AGENT_MAX_STEPS=10
BROWSEGRAB_AGENT_ENABLE_CACHE=true

QuartzUnit 生态系统的一部分

库

角色

markgrab

被动提取 (URL → Markdown)

snapgrab

被动捕获 (URL → 截图)

docpick

文档 OCR → 结构化 JSON

browsegrab

主动自动化 (目标 → 浏览器动作 → 结果)

开发

git clone https://github.com/QuartzUnit/browsegrab.git
cd browsegrab
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
playwright install chromium

# Unit tests (no browser needed)
pytest tests/ -m "not e2e"

# Full suite including E2E
pytest tests/ -v

许可证

MIT


QuartzUnit 生态系统的一部分 — 用于数据收集、提取、搜索和 AI 代理安全的可组合 Python 库。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Lightweight browser automation server for AI agents, enabling fast (10-25ms per action), structured observations and semantic selectors with zero token overhead.
      6
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      A browser automation MCP server that enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or vision models.
      24
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Provides fast, token-efficient browser automation for LLMs by attaching directly to a running Chrome instance via CDP, offering a full set of browser tools including navigation, interaction, and snapshot diffs, with batched actions to reduce round-trips.
      56
      GPL 3.0