Visual Browser Agent

ローカルファーストのブラウザ自動化ツールで、AIエージェントにウェブ操作の「目と手」を提供します。Visual Browser Agent は Playwright にエージェント制御プレーンを加えたものです。Playwright がブラウザ操作を実行し、このプロジェクトが MCP ツール、視覚的証跡、承認、Chrome アイデンティティ処理、安全制御、およびコーディングエージェントや日常のブラウザタスク向けのワークフローを追加します。

インストール後に起こること

Chromium、CDP、リモートデバッグ、Chrome の内部プロファイル名を理解する必要はありません。

技術的なインストーラが、使用しているコーディングエージェントに Visual Browser Agent を登録し、Playwright ブラウザランタイムをインストールします。その後、通常のワークフローはコーディングエージェントのチャット内で行われます。次のように言うことができます:

Use the browser to open this website and check the layout.

エージェントはまず、既存の Chrome セッションが利用可能かどうかを確認します。見つかった場合はそのセッションを使用し、見つからない場合はクリーンな Playwright 管理の Chromium セッションを起動します。また、普通の言葉で明示的に指定することもできます:

Use my Work Chrome account and check the dashboard.

エージェントは「Work — work@example.com」「Personal — personal@example.com」のような親しみやすい Chrome アイデンティティを検出します。複数のアイデンティティが存在する場合は、会話内で選択を求めます。プロファイルコマンドを実行したり、Profile 3 を選択したりする必要はありません。

Visual Browser Agent には、オプションのローカルコントロールパネルも含まれています。技術ユーザーは npx visual-browser-agent dashboard で起動できますが、通常の使用にはコントロールパネルは必要ありません。接続状態、アクティブタブ、利用可能な Chrome アイデンティティ、最近の証跡が http://127.0.0.1:8787/ に表示されます。

エージェントがログイン、メッセージ送信、公開、購入、削除、送信、外部データの変更を行う前に、一時停止して承認を求めます。読み取り専用の検査、スクリーンショット、視覚監査、証跡キャプチャは自動的に実行できます。

Related MCP server: websight

仕組み

2つのブラウザと2つの接続方法があります:

インストール

オプション 1: コーディングエージェントにインストールを依頼する

Claude Code、Cursor、Copilot、Codex、Gemini、Windsurf、Cline、Roo、Kiro、Goose、OpenCode、Antigravity、その他の MCP 対応コーディングエージェントで、次のように依頼します:

Install Visual Browser Agent, set it up for this coding agent, and check that the browser runtime is ready. Ask me before installing software or changing browser settings.

エージェントはセットアップ状態を確認し、Playwright Chromium のインストール前に確認を求め、MCP サーバーを登録し、不足している権限や拡張機能の手順を報告する必要があります。その後、「ブラウザを使って…」と言うだけで済みます。

オプション 2: GitHub から（テスト推奨）

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install dependencies
npm install

# Build
npm run build

# Initialize (installs Chromium + MCP + skills)
npx visual-browser-agent init

または npx で直接使用:

npx github:Akakaui/visual-browser-agent init

オプション 3: npm から（公開後）

# Install globally
npm install -g visual-browser-agent

# Or use directly with npx
npx visual-browser-agent init

オプション 4: ローカル開発

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install in development mode
npm install

# Build
npm run build

# Link for global use
npm link

# Now you can use it anywhere
visual-browser-agent init

クイックスタート

1. 初期化

npx visual-browser-agent init

これにより:

• Chromium（Playwright ブラウザ）をインストール

• MCP 設定をセットアップ

• Agent Skills をインストール

• コーディングエージェントを自動検出してラッパーをインストール

2. 使用開始

# Start MCP server with Chromium (default)
npx visual-browser-agent mcp

# Or start with Chrome extension
npx visual-browser-agent mcp --extension

3. AI エージェントで使用

エージェントに「このウェブサイトのデザインを調査して」と依頼します。

エージェントは Visual Browser Agent を使用してブラウザを制御します。

既存の Chrome を使用（拡張機能）

プロファイル切り替え、検証、トラブルシューティングを含む完全な一般ユーザー向けウォークスルーは、EXTENSION_INSTALLATION.md を参照してください。

エージェントに既存の Chrome（ログイン、Cookie、セッションを含む）を使用させたい場合:

1. 拡張機能をインストール

1. Chrome を開く → chrome://extensions/

2. デベロッパーモードを有効にする

3. パッケージ化されていない拡張機能を読み込むをクリック

4. 選択: node_modules/visual-browser-agent/browser-extension

2. エージェントを起動

npx visual-browser-agent mcp --extension

3. AI エージェントで使用

エージェントに「Gmail にログインしてメールを要約して」と依頼します。

エージェントは、すべてのログイン情報が保持されたあなたの Chrome に接続します。

AI エージェントとの統合

自動検出（推奨）

npx visual-browser-agent init を実行すると、自動的に:

• 使用中のコーディングエージェントを検出

• 適切なラッパーをインストール

• MCP 設定をセットアップ

手動インストール

自動検出が機能しない場合は、手動でインストールできます:

# Install for specific agent
npx visual-browser-agent host <agent-name>

対応エージェント:

• claude-code

• cursor

• gemini

• opencode

• antigravity

• windsurf

• cline

• roo

• kiro

• copilot

• codex

• goose

Claude Code

.claude/settings.json に追加:

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

Cursor

.cursor/mcp.json に追加:

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

Chrome 拡張機能モードの場合

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp", "--extension"]
    }
  }
}

AI エージェントの使用方法

シナリオ 1: 公開ウェブサイトの調査

エージェントの思考: 「これは公開ウェブサイトで、ログインは不要だ。」

エージェントの行動: Chromium（デフォルト）を使用

npx visual-browser-agent mcp

シナリオ 2: ユーザーのプライベートデータへのアクセス

エージェントの思考: 「これにはユーザーのログインが必要だ。」

エージェントの行動: 拡張機能経由で Chrome を使用

npx visual-browser-agent mcp --extension

シナリオ 3: ユーザーがブラウザを指定

ユーザーの発言: 「サインイン済みの Work Chrome アカウントを使って」

エージェントの行動:

npx visual-browser-agent mcp --choose-profile

コマンドリファレンス

一般ユーザー向けコントロールパネル

非技術ユーザーの場合、ブラウザエージェントは管理者またはコーディングエージェントのセットアップによって一度インストールおよび登録される必要があります。その後、ユーザーはコーディングエージェントに「このウェブサイトを開いて」「Work アカウントを使って」「ページを確認してスクリーンショットを見せて」などと話しかけるだけで作業できます。エージェントは MCP を通じて接続、アイデンティティ検出、証跡、承認を処理します。

オプションのローカルコントロールパネルは、接続の可視性と復旧のために利用できます。技術ユーザーは npx visual-browser-agent dashboard で起動でき、http://127.0.0.1:8787/ で開き、接続状態、親しみやすい Chrome アイデンティティ、アクティブタブ、最近の証跡を表示します。パネルはローカルのみで、コーディングエージェントの会話を置き換えるものではありません。

Playwright 2.0 互換性サーフェス

Visual Browser Agent は、エージェントワークフロー向けに Playwright ベースの MCP サーフェスを公開します。ナビゲーション、フォーム、アップロード、ダウンロード、スクリーンショット、録画、レスポンシブ監査、視覚調査に加えて、エージェントはタブ/ページ、履歴、ドラッグ＆ドロップ、ロケーター参照、ウェブファーストアサーション、フレーム検査、ダイアログポリシー、Cookie、承認済みストレージ状態のエクスポート、最近のコンソールメッセージ、最近のネットワークリクエスト、URL ルーティングモック、トレース、メディアエミュレーション、PDF 証跡、確認ゲート付きページ評価を使用できます。

互換性レイヤーは、機密操作を意図的に明示的に保ちます。Cookie のクリアには confirm=true が必要です。ページ評価には confirmDangerous=true が必要です。公開送信とアーティファクト削除は、承認サービスによって管理されたままです。ネットワークモックとストレージアーティファクトは、アクティブなエージェントセッションと承認済みディレクトリに制限されます。

プロファイル

複数の Chrome プロファイルがある場合は、拡張機能で使用するサインイン済みアカウントを選択します:

# Choose an account interactively
npx visual-browser-agent mcp --choose-profile

# Advanced: use a known technical profile name
npx visual-browser-agent mcp --profile "Profile 3"

トラブルシューティング

Chromium が動作しない

npx playwright install chromium

Chrome 拡張機能が接続しない

1. Chrome が開いていることを確認

2. 拡張機能アイコンが「ON」になっているか確認

3. 試す: npx visual-browser-agent doctor

MCP サーバーが起動しない

# Check environment
npx visual-browser-agent doctor

# Reinstall
npx visual-browser-agent init

アーキテクチャ

User's AI Agent (Claude Code, Cursor, etc.)
                    |
                    | MCP Protocol
                    |
        Visual Browser Agent MCP Server
                    |
        +-----------+-----------+
        |                       |
    Chromium                  Chrome
    (Playwright)            (Extension)
        |                       |
        v                       v
  Agent controls           Agent connects
  fresh browser            to existing browser

ライセンス

MIT

非技術ユーザー向けの日常使用

Visual Browser Agent は、2つの簡単なモードで使用できます:

非技術ユーザーは MCP を理解する必要はありません。一度セットアップすれば、コーディングエージェントに普通の言葉で指示できます。例:「Work Chrome プロファイルを開いて、この URL のチェックアウトページを検査し、スクリーンショットを保存して」または「クリーンな Chromium セッションを使って、このウェブサイトをデスクトップとモバイルで比較して」。ラッパーはコーディングエージェントに、ブラウザ接続の確認、適切なモードの選択、認証や重要な操作の前に確認を求めること、簡潔な結果と証跡を返すことを指示します。

Chrome プロファイル: 拡張機能とリモートデバッグ

Chrome 拡張機能はChrome プロファイルごとにインストールされ、ブラウザウィンドウ全体に対して一度だけではありません。拡張機能モードで3つの別々の Chrome プロファイルを使用したい場合は、各プロファイルを開き、chrome://extensions/ に移動し、デベロッパーモードを有効にして、各プロファイルで一度だけ browser-extension/ ディレクトリを読み込む必要があります。同じ拡張機能ソースをすべてのプロファイルに読み込むことができますが、各プロファイルが独自の権限を付与し、そのプロファイルが選択されている間は開いたままにする必要があります。

リモートデバッグは異なります。特定の --profile-directory とデバッグポートで起動された Chrome インスタンスに接続します。ほとんどのユーザーは visual-browser-agent mcp --choose-profile を実行するべきです。このツールは Chrome から親しみやすいアカウントラベルを読み取り、ユーザーが番号で選択できるようにします。技術的な --profile オプションは、スクリプトや高度なセットアップ用に引き続き利用できます。別の Chrome プロセスで使用中のプロファイルは、2回目の起動を拒否する場合があります。そのプロファイルを先に閉じるか、別のデバッグプロファイルとポートを使用してください。

既存のログイン Cookie が必要なユーザーには、通常拡張機能ルートが最も簡単です。再現可能なクリーンブラウザが必要なユーザーには、Chromium がより安全です。リモートデバッグは、選択したブラウザセッションをローカルエージェントプロセスに公開するため、高度なオプションとして扱うべきです。

プロンプトによるブラウザエージェントの選択

ユーザーは通常、ブラウザモードや専門モデルではなくタスクを選択します。Claude、Cursor、Copilot、Codex、Gemini、Windsurf、Cline、Roo、Kiro、Goose、OpenCode、Antigravity、またはMCP対応の他のコーディングエージェントで「ブラウザを使って…」と指示します。ラッパーはエージェントに、自動ブラウザ選択を使用し、必要に応じて表示中のChromeプロファイルを検出し、既存のセッションがない場合は管理対象のChromiumにフォールバックするよう指示します。統合がインストールされた後、コーディングエージェントはVisual Browser Agent MCPツールを選択します。プロンプトでは、重要となる場合にセッション要件を明示する必要があります：

Use a clean Chromium browser. Audit this public website at desktop and mobile widths and save visual evidence.

Use the Work account I choose from Chrome. Open the internal dashboard, inspect the layout, and ask me before making any changes.

Use the current browser session. Do not submit forms, publish, purchase, delete, or send messages without asking for approval first.

チームが名前付きのブラウザ専門エージェントを希望する場合は、コーディングクライアント用にvisual-browser-agent host <agent-name>を実行し、生成されたMCP設定とラッパーをそのプロジェクトに保持します。このパッケージには、Claude Code、Cursor、Gemini、Windsurf、Cline、Roo、Kiro、Copilot、Codex、Goose、OpenCode、Antigravity用のアダプターが含まれており、専用ラッパーのないホストにはユニバーサルラッパーを使用します。新しいホストは同じ標準MCP設定を使用できます：コマンドvisual-browser-agent mcp --managedを起動し、visual-browserという名前のMCPサーバーとして登録します。

初回セットアップの推奨手順

npm install
npm run build
npx visual-browser-agent init --mode chromium
npx visual-browser-agent host <your-coding-agent>

その後、コーディングエージェントを再起動し、ビジュアルブラウザツールを使用するよう依頼します。クリーンな日常のChromiumワークフローには、visual-browser-agent mcp --managedを使用します。既存のChromeプロファイルを使用する場合は、拡張機能を目的のプロファイルに読み込んだ後、visual-browser-agent mcp --choose-profileを使用します。--profileは高度なスクリプトにのみ使用します。

エージェントはWebサイトをレビューする際、常に読み取り専用の検査とスクリーンショットを自動的に使用する必要があります。外部データの投稿、公開、購入、削除、送信、変更の前に、明示的な承認を要求する必要があります。認証情報とプライベートな個人情報は、プロンプトや設定ファイルに配置するのではなく、ユーザーがブラウザで直接入力する必要があります。

エージェントアーティファクト、アーティファクトパネル、質問、承認

完全な一般ユーザーおよび技術ワークフローについては、Visual Browser Agent 1.0ユーザーガイドをお読みください。簡単に言うと、コーディングエージェントはMCPを通じてVisual Browser Agentと対話します：利用可能なブラウザツールを発見し、ユーザーのリクエストに一致するツールを選択し、テキスト、構造化JSON、スクリーンショット、証拠メタデータを受け取ります。

Visual Browser Agentは、UIベースのコーディングエージェントとCLIベースのエージェントの両方に対応するように設計されています。Claude CodeやAntigravityなどのUIホストは、スクリーンショット/画像コンテンツと生成されたHTMLまたはMarkdownの証拠レポートをアーティファクトパネルに配置できます。CLIホストまたは汎用MCPクライアントは、埋め込み画像ブロック、構造化メタデータ、ローカル証拠パス、またはhttp://127.0.0.1:8787/のローカルダッシュボードを通じて同じ結果を使用できます。エージェントは、ホストが任意のサンドボックスパスを開けると想定してはなりません。移植可能な結果とフォールバックを返す必要があります。

優れたブラウザエージェントの結果には、タスクの目的、URLとオリジン、選択されたブラウザプロファイル、実行されたアクション、アサーション、スクリーンショット、コンソール/ネットワークの所見、実行ID、タイムスタンプ、次のステップが含まれます。これにより、ユーザーは生のツールログを読むのではなく、視覚的に作業を検証できます。必要に応じて、エージェントにこれを明示的に依頼してください：

Create a host-renderable visual report with screenshots, assertions, console errors, and a concise conclusion. Also provide a local fallback.

人間との対話には3種類あります。質問は、どのChromeプロファイルまたはタブを使用するかなど、不足している情報を解決します。人間による引き継ぎは、パスワード、MFAプロンプト、CAPTCHA、またはワンタイムコードが表示されたときに、ユーザーにブラウザを直接操作するよう依頼します。承認は、送信、公開、購入、削除、提出などの重要なアクションを許可します。これらは意図的に分離されています：質問は行動の許可ではなく、スクリーンショットはトランザクションが成功した証拠ではありません。

フォールバックのask_humanツールは、質問と簡単な構造化選択肢をサポートします。request_approvalおよびsubmit_public_actionツールは、明示的な承認のために予約されています。エージェントは承認を求める前に、正確なサイト、ターゲット、アクション、関連データを表示し、拒否を黙って再試行するのではなく、ユーザーの最終決定として扱う必要があります。パスワード、APIキー、アクセストークン、支払い情報、ワンタイムコードをエージェントの会話に貼り付けてはなりません。完全な安全モデルについてはdocs/user-guide-1.0.md、プロファイルごとのChrome拡張機能のセットアップについてはEXTENSION_INSTALLATION.mdを参照してください。