nexus-browser-mcp

English | 简体中文

nexus-browser-mcp

イベント駆動型の決定論的スナップショットを備えた、ブラウザー自動化用 MCP サーバーです。

Playwright 上に構築されています。アクセシビリティツリーを介して LLM 用にブラウザーを操作し、移動、クリック、入力、読み取り、フォーム入力、タブ管理を行います。代替ツール（Playwright MCP など）との主な違いは次のとおりです。

1. 決定論的なスナップショット：固定間隔の sleep を推測で使うことはありません。MutationObserver が最後の DOM 変更を記録し、ブラウザー自身の requestAnimationFrame ループが、ページが STABLE_WINDOW_MS（デフォルトは 800ms）にわたって静止したと判断してからスナップショットを抽出します。これにより、「アニメーションの途中で取得される」競合を排除します。
2. 組み込みのガバナンスゲート：HITL ルール（例：「支払う／確認する」をクリックするには人間の承認が必要）、デフォルトで無効かつ常に確認が必要な browser_evaluate、JSONL 監査ログ（機密パラメーターのマスキングと、呼び出しごとの入出力文字数の計測により、トークンコストを照合できます）。
3. 複数タスクの分離：1 つの MCP 接続（セッション）で、独立した複数の task_id を実行できます。それぞれが専用の BrowserContext を持つため、ログイン状態が相互に混在しません。アイドル状態のタスクは TTL に基づいて回収され、次回使用時に再構築されて最後のページが自動的に復元されます。
4. 終了状態の可視化と自己修復：タブまたはブラウザー全体が外部から閉じられたりクラッシュしたりした場合、次の呼び出しで自動的に再構築されます（永続プロファイルによってログイン状態が維持されます）。さらに、復元されたものと失われたものをエージェントに正確に伝える [state change] 通知が先頭に追加され、Playwright の例外がそのまま漏れることはありません。
5. 開発者向けの可観測性：各ページのコンソールメッセージ、捕捉されない JS 例外、ネットワークリクエストのメタデータ（メソッド／URL／ステータス／失敗理由。本文は記録しません）を、上限付きリングバッファに記録します。browser_console／browser_errors／browser_network は since カーソルを使って差分を読み取るため、エージェントは推測せずに「何も起きなかった理由」を特定できます。

インストール

pip install nexus-browser-mcp
# or
uvx nexus-browser-mcp

実行可能なエントリーポイントとして nexus-browser-mcp と nexus-browser がインストールされます。確実に利用できる代替手段は python -m nexus_browser.server です。

playwright とそのブラウザーバイナリが必要です。

pip install playwright && playwright install chromium

統合（任意の MCP クライアント）

opencode（~/.config/opencode/opencode.json）：

{
  "mcp": {
    "browser": {
      "type": "local",
      "command": ["uvx", "nexus-browser-mcp"],
      "enabled": true
    }
  }
}

Claude Code（プロジェクトルートの .mcp.json）：

{
  "mcpServers": {
    "browser": {
      "type": "stdio",
      "command": "uvx",
      "args": ["nexus-browser-mcp"]
    }
  }
}

Pi Coding Agent：標準の MCP 設定を読み込みます。プロジェクトの .mcp.json またはユーザー共通の ~/.config/mcp/mcp.json を使用し、デフォルトのトランスポートは stdio です。

{
  "mcpServers": {
    "browser": {
      "command": "uvx",
      "args": ["nexus-browser-mcp"]
    }
  }
}

詳細は docs/INTEGRATE.md を参照してください（中国語）。

自分のブラウザーを使用する（ログイン状態を維持）

デフォルトでは、isolated モードはPlaywrightにバンドルされたChromiumを起動します。Cookieやログイン状態は引き継がれません。自分のブラウザーを使用するには、次のいずれかを選択してください。

オプションA — ブラウザープロファイルを直接読み込む（推奨、最も簡単）

普段使っているユーザーデータディレクトリ（Cookie、ログイン状態、ブックマークを含む）を使用して、システムのChromeを起動します。

BROWSER_CHANNEL=chrome
BROWSER_USER_DATA_DIR="C:\Users\<you>\AppData\Local\Google\Chrome\User Data"

注意：実際のUser Dataを使っている間は、プロセスがブラウザーを占有するため、自分でChromeを同時に起動すると競合します。プロファイルのコピーを使用するか、専用の--user-data-dirを指定してください。

推奨：ツール専用のプロファイルを使用する（日常使いのブラウザーと競合しません）

BROWSER_CHANNEL=chromeに加えて、専用のユーザーデータディレクトリ（例：C:\Users\<you>\.nexus-browser\chrome-profile）を指定します。

BROWSER_CHANNEL=chrome
BROWSER_USER_DATA_DIR="C:\Users\<you>\.nexus-browser\chrome-profile"

初回使用時に、エージェントがブラウザーツールを呼び出したときに開く専用Chromeウィンドウで、対象サイトに一度ログインします。その後はこのプロファイルにCookieが永続的に保存されるため、エージェントはログイン状態を維持しながら、普段使いのブラウザーから完全に分離された状態で動作します。

オプションB — CDP経由で実行中のChromeに接続する

まずchrome --remote-debugging-port=9222を起動し、その後BROWSER_MODE=cdpを設定します。

CDP接続に失敗した場合、サーバーは黙って新しいブラウザーに切り替えるのではなく、明示的にエラーで終了し、デバッグポート付きのブラウザーを先に起動するよう案内します。

CDP（または永続プロファイル）モードでは、エージェントはすでに開いているタブを引き継ぐこともできます。browser_list_pagesには「外部タブ」として表示され、browser_adopt_page(ext_index)でタスクに取り込めます（その後はスナップショットの取得、クリック、読み取りがすべて可能です）。引き継ぎには必ずconfirmed=trueが必要です。これにより、ログイン状態を含め、そのページへの完全な読み書きアクセス権がエージェントに付与されます。

設定（環境変数）

すべてのオプションは、BROWSER_ を接頭辞に付けた環境変数で上書きできます。

評価／全機能の使用：2 つの高リスク機能は、安全性を優先してデフォルトで無効になっています。browser_evaluate が必要な場合は BROWSER_ALLOW_JS_EXECUTION=true を設定し、browser_network_body が必要な場合は BROWSER_ALLOW_NETWORK_BODY=true を設定してください。コールドスタートでベンチマーク／評価を実行する際にこれらを有効にしない場合、該当するサブタスクは拒否されます（これは設計上の動作であり、障害ではありません）。

Variable	Default	Description
BROWSER_MODE	isolated	isolated（新しい分離ブラウザー）／cdp（お使いの Chrome に接続）
BROWSER_CDP_ENDPOINT	http://localhost:9222	CDP エンドポイント
BROWSER_CHANNEL	""	システムブラウザーのチャンネル：chrome／msedge など（空の場合は Playwright に同梱の Chromium）
BROWSER_USER_DATA_DIR	""	ユーザーデータディレクトリ（Cookie／ログイン状態を保持）。設定すると、タスク間で 1 つの永続コンテキストを共有します。空の場合は新しいプロファイルを使用します
BROWSER_HEADLESS	false	ヘッドレスモード（isolated のみ）
BROWSER_DEFAULT_TIMEOUT_MS	30000	Playwright の操作ごとのタイムアウト（ナビゲーションなど）
BROWSER_TOOL_TIMEOUT_MS	60000	ツール呼び出しごとの外側のタイムアウトガード（ハングする代わりに ERROR を返します）
BROWSER_STABLE_WINDOW_MS	800	安定性を判定する静穏期間：DOM の変更がない状態が続く時間
BROWSER_STABLE_REQUIRED	2	フォールバックのみ：MutationObserver ウォッチャーが利用できない場合に、安定性を確認するために使う連続した同一スナップショットの数（通常の経路では、変更タイムラインを直接使って「キャプチャ中に変更がゼロ」であることを確認します）
BROWSER_STABLE_TIMEOUT_MS	3000	安定性を待機する合計タイムアウト。期限切れの場合は、機能を低下させながら処理を続行します
BROWSER_SNAPSHOT_MAX_NODES	100	スナップショットあたりの最大ノード数
BROWSER_CONTEXT_TTL_SEC	600	アイドル状態のタスクを自動回収するまでの時間（秒）
BROWSER_STREAM_CHAR_CAP	16000	ストリームバッファーあたりの最大文字数（古いデータは区切りマーカーを付けて破棄）
BROWSER_STREAM_PAGE_CAP	64000	ページあたりのストリームバッファーの合計文字数
BROWSER_EVENT_MAX_ENTRIES	500	ページあたりの最大イベント数（コンソール／例外／リクエスト）。古いイベントはカウンターを付けて破棄
BROWSER_EVENT_TEXT_CAP	500	イベントごとのテキスト切り詰め文字数
BROWSER_EVENT_HANDLE_MAX	50	オンデマンドで本文を読み取るため、ライブのレスポンスハンドルを保持するページあたりの最近のリクエスト数
BROWSER_ALLOW_NETWORK_BODY	false	browser_network_body を許可します（レスポンス本文には機密データが含まれる可能性があります）
BROWSER_NETWORK_BODY_CAP	4000	レスポンス本文ごとに返す最大文字数
BROWSER_TRANSPORT	stdio	stdio／http（リモート／複数クライアント向けの streamable-http）
BROWSER_HTTP_HOST	127.0.0.1	HTTP バインドアドレス。localhost 以外を指定する場合は BROWSER_HTTP_TOKEN が必要です（設定されていない場合、起動を拒否します）
BROWSER_HTTP_PORT	8817	HTTP ポート
BROWSER_HTTP_TOKEN	""	HTTP トランスポート用の Bearer トークン
BROWSER_ALLOW_JS_EXECUTION	false	browser_evaluate を許可します（有効時は無条件で HITL を適用）
BROWSER_HITL_RULES	[]	HITL ルールの JSON 配列。例：`[{"action":"click","name_pattern":"pay
BROWSER_AUDIT_PATH	~/.nexus-browser/audit.jsonl	監査ログのパス
BROWSER_DIALOG_TIMEOUT_MS	20000	保留中の confirm／prompt を自動的に閉じるまでのタイムアウト（イベントログには履歴が保持されます）
BROWSER_DOWNLOAD_DIR	~/.nexus-browser/downloads	許可されたダウンロードの保存先（クリックするとファイル名とパスが報告されます）
BROWSER_PROXY	""	none を指定すると、--no-proxy-server を付けてブラウザーを起動します（システムプロキシをバイパス）

ツール

34 個のツール：browser_navigate、browser_navigate_back、browser_snapshot、browser_click、browser_type、browser_hover、browser_press_key、browser_select_option、browser_upload_file（HITL による確認済み）、browser_drag、browser_dialog_respond（ダイアログはエージェント／ユーザーの判断を待つ状態で保留されます。承認には confirmed=true が必要です）、browser_adopt_page（cdp／永続モードで、すでに開いているブラウザータブを引き継ぎます。HITL による確認済み）、browser_read、browser_screenshot、browser_evaluate、browser_wait、browser_wait_stable、browser_wait_ms、browser_scroll、browser_scroll_to、browser_wait_navigation、browser_find（テキストでコンテンツを検索 → refs）、browser_dismiss_popup、browser_list_pages、browser_switch_page、可観測性ツール browser_console、browser_errors、browser_network、browser_perf、browser_network_body、および 4 つのライフサイクルツール：browser_tasks、browser_close_task、browser_list_sessions、browser_close_session。

可観測性（デバッグ）：コンソール出力、捕捉されなかった例外、リクエストメタデータは、ページの作成時からページごとにバッファーに記録されます。browser_errors() は「JS 例外 + console.error + 失敗したリクエスト」をまとめたビューを 1 回の呼び出しで返します。3 つすべてが since カーソルに対応しており、省略すると前回の読み取り以降、0 を指定するとすべてが対象になります。また、ページングには limit を使用できます。

パフォーマンス：browser_perf() は FCP／LCP／CLS／INP、ナビゲーションのタイミング、および最も遅いリソース 5 件を返します。レスポンスボディは browser_network_body(seq) でオンデマンド取得できます。デフォルトでは無効（BROWSER_ALLOW_NETWORK_BODY）で、呼び出しごとに confirmed=true による確認が必要です。文字数には上限があり、ボディが監査ログに記録されることはありません。

トークンコスト：主張ではなく、実測値

同じ10ステップのタスクを、両サーバーのデフォルト設定で実行し、JSON-RPCペイロード層で計測しました（cl100k トークン数。ハーネスと生データはdocs/bench/token-comparison.mdを参照。bench/compare.pyで再現できます）。

	nexus-browser-mcp	playwright-mcp
10ステップのタスク合計	3,460 tok	26,032 tok
navigate 直後のスナップショット	65 tok	6,931 tok

全体でトークンを7.5倍削減、繰り返しのスナップショットでは100倍削減 — 実際のエージェントのループ（ポーリング、複数ステップのフォーム、状態確認）で最も大きなコストになります。

実サイトのベンチマーク（7つのシナリオ × 検証可能なサブタスク各5～7件：Baidu／Bing／DuckDuckGoの検索、Wikipediaの閲覧、Hacker News、GitHubの閲覧 — docs/bench/realworld.md）：サブタスクの完了数は37/42対31/42、トークン数は18.2k対566.4k（31倍）、実行時間は107秒対179秒 — Wikipediaの記事を1つスナップショットするだけで、nexusは上限設定と差分を使う一方、pw-mcpでは約252kトークンを消費します。エンタープライズタスクのスイート（フィルター／並べ替え、ダッシュボードの閲覧、KBの回答、複数ステップの注文、価格比較 — docs/bench/enterprise-ops.md）：3つすべてのサーバーで21/21を達成（playwright-mcpおよびchrome-devtools-mcpとの比較）；トークン数は3.6k対5.1k対10.9k。大規模テスト（106ケース／184サブタスク、3つのサーバー、シード済みの決定論的フィクスチャ — docs/bench/scale-ops.md）：完了数は184/184対180/184対178/184；トークン数は153.5k対180.5k対231.1k（1.00：1.18：1.51） — 競合製品との差は安定したゼロ件（richtext-iframeへの書き込み、ダウンロードの可観測性、右クリック）であり、ノイズではありません。

敵対的に複雑なページでの要素識別精度（同じ名前のボタンが並ぶグリッド、シャドウDOM、iframe、非表示／無効化の罠、全面再レンダリング — docs/bench/element-acc.md）：nexusは92％＝pwは92％＜chrome-devtools-mcpは100％で、コストもcdtが最小 — cdtの冗長なノードごとのダンプには、簡潔なスナップショットでは省略される製品テキストが含まれており、値に基づくターゲティングではその情報が必要です。テキストの切り詰めによる既知のトレードオフとして、これを公開しています。トークンを全体で節約しても、精度あたりのコストが抑えられなければ意味がありません。このスイートは、その指標を監視するためのカナリアです（ベンチマークで検証した改善方針：同名の候補が競合する場合に限り、兄弟要素のテキスト要約を付加します）。

HITL確認によってループが完結します。ゲート対象の呼び出しは、初回にCONFIRMATION_REQUIREDを返します。ユーザーがチャットで承認した後、エージェントはconfirmed=trueを付けて再度呼び出します（HITLルール、browser_evaluate、browser_network_bodyに適用されます）。

HTTP トランスポート（リモート／複数クライアント）

デフォルトはstdio（単一クライアント）です。リモートまたは複数クライアントで使用する場合は、ストリーム可能なHTTPサーバーを実行します。

BROWSER_TRANSPORT=http BROWSER_HTTP_PORT=8817 nexus-browser-mcp

各MCPセッションには分離されたsession_idが割り当てられます（通常どおり、タスクごとにコンテキストが分離されます）。安全規則：BROWSER_HTTP_TOKENを設定せずにlocalhost以外のアドレスにバインドすると、起動を拒否します — 認証なしでブラウザーを操作できるポートは、セキュリティ上の落とし穴です。トークンを設定した場合、リクエストにはAuthorization: Bearer <token>を指定する必要があります。

ストリーミングコンテンツ（AIの返信など）：browser_read(wait_stable=true)はDOMが静止するまで待機し、1回の呼び出しで全文を読み取ります。browser_read(selector=..., follow=true)は増分を追跡し、呼び出しごとに新しいコンテンツのみを返します（full=trueを指定するとバッファー全体を返します）。browser_wait_stable／browser_wait_msは、イベント駆動型および固定時間の待機プリミティブを提供します。

スナップショットの差分：ツリーが前回とノード単位ですべて同一のbrowser_snapshotを繰り返すと（Playwrightは世代ごとにrefsを再採番するため、refsは除外）、ツリー全体の代わりに約120文字の[no change]通知を返します。以前に発行されたrefsは世代の連鎖によって引き続き有効です。diff=falseを指定すると、完全なスナップショットを強制します。実際に変更があった場合（コンテンツ、ボックス、属性）は、完全なスナップショットを返します — 部分的なマージは行わず、古いビューも返しません。

ほとんどのツールは省略可能なtask_idを受け付けます（デフォルトは共有のdefaultタスクです）。docs/の使用ガイドを参照してください（中国語）。

開発

uv venv
uv pip install -e ".[dev]"
python -m pytest tests -q
ruff check src tests
python -m smokes.test_e2e           # real-browser smoke
python -m smokes.test_e2e_interact  # forms + multi-task smoke
python -m smokes.test_e2e_observability  # console/exception/network observability smoke

ライセンス

MIT