unbrowser

에이전트를 위한 저렴한 브라우저 패스. 단일 네이티브 바이너리. Chrome 불필요.

공식 MCP 레지스트리 ID: mcp-name: io.github.protostatis/unbrowser

unbrowser는 에이전트를 위한 상태 저장형, 비시각적 웹 런타임입니다. curl/WebFetch와 실제 브라우저 사이에 위치하며, 쿠키와 DOM 상태를 유지하고, 쿼리 가능한 요소 참조를 반환하며, 링크와 HTML 폼을 처리하고, 챌린지 및 SPA 신호를 감지하며, 정적 HTML만으로 부족할 때 제한된 QuickJS 페이지 스크립트를 실행할 수 있습니다.

기본 navigate는 빠른 정적/SSR 패스입니다. 제한된 QuickJS 실행이 필요할 때만 exec_scripts: true를 설정하세요. 무거운 SPA, 픽셀, V8 충실도, 확장 기능, 대화형 안티봇 챌린지는 실제 Chrome 계층에서 처리해야 합니다.

설치 전에 라이브 공개 웹 데모를 사용해 보세요. 이 데모는 페이지에 표시된 고정된 공개 소스 세트만 허용합니다. 개인 데이터, 쿠키, 인증된 작업을 보내지 마세요. 공개 스모크 테스트를 위해 공유 Streamable HTTP MCP 엔드포인트가 https://unchainedsky.com/unbrowser-mcp에 제공됩니다. 프로덕션 세션은 로컬 설치를 사용해야 합니다.

unbrowser는 접근이 허용된 사이트, 계정, 데이터에만 사용하세요. 챌린지 감지와 쿠키 가져오기는 접근 제어나 사이트 약관을 우회할 권한을 부여하지 않습니다. 세션 쿠키는 자격 증명으로 취급하세요. 로컬에 보관하고 승인된 작업 범위로 제한하며 공개 데모로 절대 보내지 마세요.

적절한 계층 선택

HTTP만으로는 너무 부족하고 전체 브라우저는 너무 비쌀 때 unbrowser를 사용하세요. 페이지가 Chrome을 필요로 하는 경우, 출력은 존재하지 않는 호환성을 가장하는 대신 에이전트에게 에스컬레이션을 지시합니다.

Related MCP server: Browserbase MCP Server

빠른 시작

Docker — Linux amd64/arm64, ~13 MiB pull

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이며 비루트(non-root)로 실행됩니다. 셸, 패키지 관리자, 영구 상태가 없습니다. 프로덕션에서는 :vX.Y.Z 또는 이미지 다이제스트를 고정(pin)하세요.

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이고, import와 실행 파일은 unbrowser로 유지됩니다.

MCP

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

최소 표면: "--mcp-profile", "minimal"을 추가하여 navigate/query/extract/help만 노출하고 나머지 도구는 help(topic)을 통해 에이전트가 발견하도록 하세요. Python 래퍼는 unbrowser-smart 콘솔 스크립트로 3개 도구 스마트 서버(search/open/help)를 제공합니다.

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

Cargo, 릴리스 아카이브, 소스 빌드, 영구 셸 세션, 원시 JSON-RPC, 모든 MCP 옵션에 대한 자세한 내용은 설치 및 인터페이스 참조를 참조하세요.

에이전트가 얻는 것

• navigate는 BlockMap을 반환합니다: 페이지 타이틀, 랜드마크, 헤딩, 인터랙티브 요소, 밀도 신호, ASCII 개요를 포함합니다. 크기는 페이지에 따라 달라지며, 고정 토큰 약속이 아닌 계획 수립을 위한 구조화된 형태입니다.

• 안정적인 요소 참조 (e:142): 요소를 한 번 쿼리한 다음, HTML을 다시 파싱하지 않고 해당 요소에 click, type, submit을 수행할 수 있습니다.

• 상태 저장형 쿠키와 폼: 쿠키 저장소(cookie jar), GET 및 URL 인코딩 POST 폼 제출, 링크, 리디렉션이 세션 내에서 유지됩니다.

• 페이지 및 챌린지 신호: density.likely_js_filled, thin_shell, challenge.provider는 에이전트에게 스크립트를 실행할지, 포함된 데이터를 검사할지, 중지할지, 승인된 브라우저 세션으로 에스컬레이션할지 알려줍니다.

• 모든 결과에 포함된 라우팅 보조: 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를 설정하면 인라인 및 외부 스크립트가 제한된 watchdog 아래에서 QuickJS로 실행됩니다. 이는 가벼운 하이드레이션과 fetch로 조회 가능한 데이터를 구체화할 수 있지만, V8이나 렌더링 엔진은 아닙니다. 무거운 React/Vue/Ember 앱은 여전히 빈 셸을 남길 수 있습니다.

허용된 작업에 실제 픽셀, Canvas/WebGL, Workers, 브라우저 확장 기능, V8 호환성, 인증된 프로필 또는 사람의 확인이 필요한 경우 unchainedsky-cli 또는 Unchained으로 에스컬레이션하세요. 사용자가 이미 Chrome에서 승인된 세션을 구축한 경우 cookies_set은 필요한 세션 쿠키를 만료될 때까지 로컬로 가져올 수 있습니다. 이것은 사이트의 통제를 우회할 수 있는 권한이 아닙니다.

문서

라이선스

Apache-2.0 — LICENSE를 참조하세요.