Chromeをフルインストールすることなく、Cookie、DOMの状態、HTMLフォームを処理できる、エージェント向けの軽量な非視覚的Webランタイムを提供します。
別名 protostatis/unbrowser, unbrowser, pyunbrowser
- スター
- 17
- ツール
- —
- ダウンロード数(30日間)
- 551
- 最新バージョン
- 0.0.21
- 最終コミット
- 2026年8月21日
- ライセンス
- Apache-2.0
unbrowser MCPとは
Chromeをフルインストールすることなく、Cookie、DOMの状態、HTMLフォームを処理できる、エージェント向けの軽量な非視覚的Webランタイムを提供します。
プロジェクトのREADMEから生成された概要
unbrowser MCP server について
unbrowserは、単純なHTTP fetchよりも高い機能が必要でありながら、フルサイズのChromeインストールよりもオーバーヘッドを抑えたいAIエージェント向けに設計された、軽量な非視覚的Webランタイムを提供します。Cookieの維持、DOM状態の管理、セッション内でのHTMLフォームやリンクの処理を行う、ステートフルな中間層として機能します。開発者は、ネイティブバイナリ、pyunbrowserという名称のPythonパッケージ、またはdistroless Dockerイメージを通じてローカルにデプロイできます。
ユーザーは、stdioを介したMCP接続、またはテスト用に共有されたstreamable HTTPエンドポイントを利用してサーバーに接続します。このランタイムには、エージェントがWebコンテンツとやり取りするためのnavigate、query、extractなどのツールが含まれています。静的なHTMLでは不十分な場合にページスクリプトを実行できるよう、制限付きのQuickJSエンジンを搭載していますが、これはフル機能のV8エンジンの代わりになるものではありません。エージェントが複雑なインタラクティブ要素や、負荷の高いシングルページアプリケーションに遭遇した場合、サーバーはタスクを実際のブラウザに引き継ぐよう提案する特定のシグナルを提供します。
できること
- 1複雑なWebフォームの操作このランタイムにより、エージェントはCookieの永続化や、GETまたはPOSTフォームの送信を含むセッションを管理できます。
- 2アンチボットやSPA要件の検知サイトがフルブラウザを必要とする場合、サーバーは課題(challenges)や空のシェルに関するシグナルを提供することで、エージェントに通知します。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
unbrowser MCPのインストール方法
フォーマット検証日 2026年11月10日Cursor に追加Gooseに追加Claude Codeにunbrowser MCPをインストール
$ claude mcp add unbrowser -- uvx pyunbrowserCursorにunbrowser MCPをインストール
~/.cursor/mcp.json
{
"mcpServers": {
"unbrowser": {
"command": "uvx",
"args": [
"pyunbrowser"
]
}
}
}VS Codeにunbrowser MCPをインストール
.vscode/mcp.json
{
"servers": {
"unbrowser": {
"type": "stdio",
"command": "uvx",
"args": [
"pyunbrowser"
]
}
}
}VS Code CLIにunbrowser MCPをインストール
$ code --add-mcp '{"name":"unbrowser","type":"stdio","command":"uvx","args":["pyunbrowser"]}'Claude Desktopにunbrowser MCPをインストール
claude_desktop_config.json
{
"mcpServers": {
"unbrowser": {
"command": "uvx",
"args": [
"pyunbrowser"
]
}
}
}Codexにunbrowser MCPをインストール
$ codex mcp add unbrowser -- uvx pyunbrowserCodex config.tomlにunbrowser MCPをインストール
~/.codex/config.toml
[mcp_servers.unbrowser] command = "uvx" args = ["pyunbrowser"]
Gemini CLIにunbrowser MCPをインストール
$ gemini mcp add -s user unbrowser uvx -- pyunbrowserGemini settings.jsonにunbrowser MCPをインストール
~/.gemini/settings.json
{
"mcpServers": {
"unbrowser": {
"command": "uvx",
"args": [
"pyunbrowser"
]
}
}
}自動チェック
実行日 2026年11月14日完全なレポート →自動チェックに合格しました。これはセキュリティ監査ではありません。コードを読み、サーバーに必要最小限のアクセス権を与えてください。 チェックの仕組み
- ソースリポジトリがリンクされており、アクセス可能protostatis/unbrowser is public and reachablegithub.com/protostatis/unbrowser ↗合格
- パッケージがこのリポジトリをソースとして指定pyunbrowser names protostatis/unbrowser as sourcepypi.org/project/pyunbrowser/ ↗合格
- ビルドの来歴 (Sigstore 証明)Sigstore attestation for pyunbrowserpypi.org/project/pyunbrowser/ ↗合格
- オープンソースライセンス (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-08-21github.com/protostatis/unbrowser ↗合格
- OpenSSF Scorecard未チェック
- パッケージ名が有名なパッケージに酷似していないNo popular package one edit away from pyunbrowser合格
- パッケージおよびその依存関係に重大な勧告なし1 resolved dependencies checked; no critical advisoryosv.dev ↗合格
- モデルへの隠れた指示がない0 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされている未チェック
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るunbrowser
The cheap browser pass for agents. One native binary. No Chrome.
Official MCP Registry identity: mcp-name: io.github.protostatis/unbrowser
unbrowser is a stateful, non-visual web runtime for agents. It sits between curl/WebFetch and a real browser: it retains cookies and DOM state, returns queryable element refs, handles links and HTML forms, detects challenge and SPA signals, and can run bounded QuickJS page scripts when static HTML is not enough.
Default
navigateis a fast static/SSR pass. Setexec_scripts: trueonly when you need bounded QuickJS execution. Heavy SPAs, pixels, V8 fidelity, extensions, and interactive anti-bot challenges belong in a real Chrome tier.
Try the live public-web demo before installing. It accepts only the fixed public source sets shown on the page; do not send private data, cookies, or authenticated tasks through it. A shared Streamable HTTP MCP endpoint is available at https://unchainedsky.com/unbrowser-mcp for public smoke tests; production sessions should use a local install.
Use unbrowser only on sites, accounts, and data you are permitted to access.
Challenge detection and cookie import do not grant permission to bypass access
controls or site terms. Treat session cookies as credentials: keep them local,
scope them to the authorized task, and never send them to the public demo.
Pick the right tier
| Need | curl / WebFetch | unbrowser | Real Chrome |
|---|---|---|---|
| Static / SSR HTML | raw response | structured BlockMap + DOM queries | full browser |
| Cookies, links, HTML forms | DIY | built in | built in |
| Client-side page scripts | ❌ | bounded QuickJS, opt-in | V8 |
| Pixels, Canvas, WebGL, Workers, extensions | ❌ | ❌ | ✅ |
| Agent-oriented output | DIY parsing | element refs, page signals, structured extraction | DIY CDP / DOM parsing |
| Interactive access challenge | ❌ | detect + stop or escalate | authorized browser / human confirmation |
Use unbrowser when HTTP alone is too dumb and a full browser is too expensive. When the page needs Chrome, the output tells the agent to escalate rather than pretending compatibility it does not have.
Quick start
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
The image is distroless and runs as non-root: no shell, package manager, or persistent state. Pin :vX.Y.Z or an image digest in production.
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"])
On macOS, /usr/bin/python3 is 3.9 and cannot install the wheel; use pipx or a Homebrew Python. The PyPI distribution is pyunbrowser, while the import and executable remain unbrowser.
MCP
{
"mcpServers": {
"unbrowser": {
"command": "unbrowser",
"args": ["--mcp"]
}
}
}
Minimal surface: add "--mcp-profile", "minimal" to expose only navigate/query/extract/help and let the agent discover the rest via help(topic). The Python wrapper ships a 3-tool smart server (search/open/help) as the unbrowser-smart console script.
{
"mcpServers": {
"unbrowser": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"ghcr.io/protostatis/unbrowser:latest"
]
}
}
}
See installation and interface reference for Cargo, release archives, source builds, persistent shell sessions, raw JSON-RPC, and all MCP options.
What an agent gets
navigatereturns a BlockMap: page title, landmarks, headings, interactives, density signals, and an ASCII outline. Its size is page-dependent; it is structured for planning rather than a fixed-token promise.- Stable element refs (
e:142): query an element once, thenclick,type, orsubmitit without re-parsing HTML. - Stateful cookies and forms: cookie jar, GET and URL-encoded POST form submission, links, and redirects persist within a session.
- Page and challenge signals:
density.likely_js_filled,thin_shell, andchallenge.providertell an agent whether to run scripts, inspect embedded data, stop, or escalate to an authorized browser session. - Routing aids on every result:
micro_hint(the single next concrete step),next_tools(ranked candidates),avoid(tools with nothing to act on), and a stableescalationtaxonomy (challenge,thin_shell,partial_result, …) with retryable/severity/evidence — recommendations never contradictavoid. - Structured helpers: route discovery, card extraction, table normalization,
text_main, and selector debugging cover common extraction workflows.
Script mode and escalation
{"id":1,"method":"navigate","params":{"url":"https://example.com","exec_scripts":true}}
With exec_scripts: true, inline and external scripts run in QuickJS under a bounded watchdog. This can materialize light hydration and fetch-visible data; it is not V8 or a rendering engine. Heavy React/Vue/Ember apps may still leave an empty shell.
Escalate to unchainedsky-cli or Unchained when a permitted task needs real pixels, Canvas/WebGL, Workers, browser extensions, V8 compatibility, an authenticated profile, or human confirmation. When the user has already established an authorized session in Chrome, cookies_set can import the required session cookie locally until it expires; it is not a license to circumvent a site's controls.
Documentation
| Need | Read |
|---|---|
| Install paths, session CLI, one-shot CLI, raw RPC, MCP, shims, full RPC table | Usage reference |
| Script compatibility, SPA signals, challenge handling, authorized cookie handoff, escalation | Compatibility and escalation |
| Distribution and supported directory listings | Distribution notes |
| Build the native binary | Build instructions |
License
Apache-2.0 — see LICENSE.
unbrowser MCPのよくある質問
unbrowser MCPをClaude Codeに追加するには
ターミナルでclaude mcp add unbrowser -- uvx pyunbrowserを実行します。すべてのプロジェクトで利用するには--scope userを追加します。
unbrowser MCPをCursorに追加するには
~/.cursor/mcp.jsonを開き、上記のインストールセクションに示すCursor設定を使ってmcpServersの下にサーバーを追加します。
JavaScriptを実行できますか?
はい、exec_scriptsパラメータを有効にすることで、制限付きのQuickJSページスクリプトを実行できます。ただし、フル機能のV8エンジンではありません。
代わりに本物のChromeブラウザを使用すべき時はいつですか?
ピクセル、Canvas、WebGL、worker、拡張機能、または高いV8互換性が必要な場合は、実際のブラウザへの切り替えを検討してください。
Pythonでのインストール方法は?
pipxを使用して 'pipx install pyunbrowser' と入力するか、pipを使用して 'pip install pyunbrowser' でインストールできます。