MCP Browser Use

このMCPで実現できること

このプロジェクトは、Model Context Protocol (MCP) と Selenium を使用して、AIエージェントがWeb利用、ブラウザ自動化、スクレイピング、自動化を実行できるようにすることを目的としています。

このMCPの特別な機能は、複数のエージェントが複数のブラウザウィンドウにアクセスできることです。複数のスクレイピングエージェントを動かすために、複数のDockerイメージ、VM、またはコンピュータを起動する必要はありません。また、すべてのエージェントで単一のブラウザプロファイルを使用し続けることができます。各エージェントは独自のウィンドウを持ち、互いに干渉することはありません。

これにより、複数のエージェントの管理がシームレスになります。必要なだけエージェントを起動すれば、そのまま動作します！ 2つのClaude Codeインスタンス、1つのCodex CLIインスタンス、1つのGemini CLIインスタンス、そして fast-agent インスタンスをすべて1台のコンピュータ上で、すべて同じブラウザプロファイルを使用して、（ある程度）並行して動作させることができます。

私たちの使命は、AIエージェントが自然言語の指示に基づいて、最小限の人間による監視でWebタスクを完了できるようにすることです。

Related MCP server: Selenium MCP Server

特徴

• HTMLの切り詰め: このMCPでは、HTMLページの切り詰めを設定できます。他のスクレイピングMCPでは、コンテキストウィンドウよりも大きなアクセシビリティスナップショットやHTMLダンプでAIを圧倒してしまう可能性があります。このMCPでは、環境変数 MCP_MAX_SNAPSHOT_CHARS を設定することで、最大ページサイズを管理できます。

• 複数のブラウザウィンドウと複数のエージェント: エージェント側での調整を必要とせず、複数のエージェントをこのMCPに個別に接続できます。各エージェントは同じブラウザプロファイルで作業できるため、エージェント間でログイン状態を維持したい場合に便利です。各エージェントは独自のブラウザウィンドウを持つため、互いに干渉しません。Chrome DevTools ProtocolのTargetIdを使用してブラウザウィンドウを識別します。

既知の制限事項

• Iframeコンテキスト: iframe内での複数ステップのインタラクションでは、各アクションに対して iframe_selector を指定する必要があります。信頼性を確保するため、ブラウザのコンテキストはツール呼び出しごとにリセットされます。iframeワークフローの場合は、click_element、fill_text、または debug_element の各呼び出しでiframeセレクターパラメーターを繰り返してください。

設定 / インストール

1. クローンして仮想環境を作成する

git clone https://github.com/janspoerer/mcp_browser_use.git
cd mcp_browser_use
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Chrome Betaをインストールする

AIエージェントが日常的なブラウジングに干渉することなくリモートデバッグを実行できるように、通常のChromeではなくChrome Betaを使用することをお勧めします。

macOS:

brew install --cask google-chrome-beta

Ubuntu / Debian:

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" \
    | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-beta

Windows: google.com/chrome/beta からChrome Betaをダウンロードしてインストールします。

インストール後、以下を確認してください:

google-chrome-beta --version      # Linux
# or
"/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta" --version  # macOS

Linuxヘッドレスサーバー — Xvfb (仮想ディスプレイ)

Chromeにはディスプレイが必要です。ヘッドレスLinuxサーバー（GUIなし）では、Xvfbを使用します:

sudo apt install -y xvfb

# Start a virtual display on screen :99
Xvfb :99 -screen 0 1920x1080x24 &

# Tell Chrome which display to use
export DISPLAY=:99

永続化するには、.bashrc または .profile に export DISPLAY=:99 を追加してください。

3. 設定と起動

• Chrome Betaをインストールした後、以下の「環境変数の設定」セクションで説明されているように、.mcp.json でChrome Betaの実行ファイルを指定します。

• MCPサーバーを起動します（方法がわからない場合は、以下の「このMCPの使い方」セクションを確認してください）。

このMCPの使い方

modelcontextprotocol.ioのMCPドキュメントを参照してください。

MCP設定ファイルが指し示すPython環境にすべての依存関係をインストールする必要があることに注意してください。たとえば、python または python3 実行ファイルを指定した場合、グローバルなPython環境を指すことになります。通常は、以下のような仮想環境を指定することをお勧めします:

/Users/yourname/code/mcp_browser_use/.venv/bin/python

このリポジトリをローカルの code フォルダーにクローンした場合、MCP設定ファイルは次のようになります:

{
    "mcpServers": {
        "mcp_browser_use": {
            "command": "/Users/janspoerer/code/mcp_browser_use/.venv/bin/python",
            "args": [
                "/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"
            ]
        }
    }
}

（macOSの場合）場所は /Users/janspoerer/Library/Application Support/Claude/claude_desktop_config.json です。

インストールが必要な依存関係については、requirements.txt を参照してください。

Claudeを再起動して、JSON設定が有効かどうかを確認します。何らかの問題がある場合、ClaudeがMCPのエラーログへ案内します。

セットアップが成功すると、Claudeの「New Chat」ウィンドウの右下に小さなハンマーアイコンが表示されます。ハンマーの横には、MCPが提供する関数の数が表示されます。

ハンマーをクリックして、利用可能なツールを確認してください。

環境変数の設定

重要: すべての環境変数は、.env ファイルではなく、プロジェクトルートの .mcp.json ファイルで定義してください。これにより、競合のない単一の信頼できる情報源が確保されます。

推奨設定 (Chrome Beta)

.mcp.json ファイルの env セクションに環境変数を追加します:

{
  "mcpServers": {
    "mcp_browser_use": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "mcp_browser_use"],
      "env": {
        "BETA_PROFILE_NAME": "SeleniumProfile",
        "BETA_EXECUTABLE_PATH": "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
        "BETA_PROFILE_USER_DATA_DIR": "/Users/yourname/Library/Application Support/Google/Chrome Beta",
        "CHROME_REMOTE_DEBUG_PORT": "9225",
        "MCP_HEADLESS": "0",
        "MCP_ENABLE_EXTENSIONS": "1",
        "MAX_SNAPSHOT_CHARS": "10000"
      }
    }
  }
}

Windowsの例:

"env": {
  "BETA_PROFILE_NAME": "SeleniumProfile",
  "BETA_EXECUTABLE_PATH": "C:\\Program Files\\Google\\Chrome Beta\\Application\\chrome.exe",
  "BETA_PROFILE_USER_DATA_DIR": "C:\\Users\\yourname\\AppData\\Local\\Google\\Chrome Beta\\User Data",
  "CHROME_REMOTE_DEBUG_PORT": "9225",
  "MCP_HEADLESS": "0",
  "MCP_ENABLE_EXTENSIONS": "1"
}

環境変数リファレンス

なぜChrome Betaを使うのか？

Chrome Beta（またはCanary）を使用することで、通常のChromeブラウザとの競合を防ぐことができます:

• AIエージェントは、リモートデバッグを有効にしてChromeを実行する必要があります

• 通常のChromeインスタンスは、リモートデバッグを有効にして実行できません

• Chrome Betaを使用すると、同じシステム上で両方を共存させることができます

プロファイルの推奨事項

• "Default" ではなく "SeleniumProfile" のような専用プロファイルを使用してください

• これにより、Chrome Betaを手動で開いた場合の競合を防ぎます

• 拡張機能とログイン状態はこのプロファイル内でセッションをまたいで保持されます

• 各AIエージェントは独自のブラウザウィンドウを持ちますが、プロファイルは共有されます

利用可能なツール

デバッグ

メインブラウザ（自動化ブラウザではない）で以下のURLにアクセスし、ブラウザが実行されているか確認してください:

http://127.0.0.1:9223/json/version

ブラウザが実行されている場合、以下のように表示されます:

{
   "Browser": "Chrome/140.0.7339.24",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
   "V8-Version": "14.0.365.3",
   "WebKit-Version": "537.36 (@f8765868e23d9ee5209061fc999f6495c525cd13)",
   "webSocketDebuggerUrl": "ws://127.0.0.1:9223/devtools/browser/d8f511eb-947c-4eb1-833d-917212a92394"
}

ロックファイルと調整

このMCPは、ファイルベースのロックを使用して、同じブラウザプロファイルにアクセスする複数のエージェントを調整します。すべてのロックファイルは、検査しやすいようにプロジェクトルートディレクトリの tmp/mcp_locks/ に保存されます。

ロックファイルの種類

アクションロック (<hash>.softlock.json および <hash>.softlock.mutex)

• 一度に1つのエージェントのみがブラウザアクションを実行できるようにします

• デフォルトTTL: 30秒 (MCP_ACTION_LOCK_TTL で設定可能)

• エージェントが作業中はハートビートで自動的に更新されます

• エージェントはロックを取得するために最大60秒待機します (MCP_ACTION_LOCK_WAIT で設定可能)

ウィンドウレジストリ (<hash>.window_registry.json)

• どのエージェントがどのブラウザウィンドウを所有しているかを追跡します

• 内容: targetId、windowId、プロセスPID、最後のハートビートタイムスタンプ

• オーファン（孤立）クリーンアップに使用: クラッシュ/停止したエージェントのウィンドウを自動的に閉じます

• 期限切れしきい値: 5分 (MCP_WINDOW_REGISTRY_STALE_SECS で設定可能)

スタートアップミューテックス (<hash>.startup.mutex)

• プロファイルごとに単一のブラウザインスタンスの起動を保証します

• 初期のChromeプロセス起動調整中に使用されます

ファイル形式: <hash> は、Chromeプロファイルの user_data_dir と profile_name から導出されたSHA-256ハッシュであり、プロセス間で安定した識別を保証します。

設定

以下の環境変数でロック動作をカスタマイズできます:

# Lock directory (default: <project_root>/tmp/mcp_locks/)
MCP_BROWSER_LOCK_DIR=/path/to/locks

# Action lock TTL in seconds (default: 30)
MCP_ACTION_LOCK_TTL=30

# Max wait time for action lock in seconds (default: 60)
MCP_ACTION_LOCK_WAIT=60

# Window registry stale threshold in seconds (default: 300)
MCP_WINDOW_REGISTRY_STALE_SECS=300

# File mutex stale threshold in seconds (default: 60)
MCP_FILE_MUTEX_STALE_SECS=60

オーファンウィンドウのクリーンアップ

エージェントがブラウザセッションを開始すると、自動的に以下が行われます:

1. 停止したプロセス（PIDが存在しない）からのエントリがないかウィンドウレジストリを確認

2. 期限切れのエントリ（5分以上ハートビートがない）を確認

3. Chrome DevTools Protocolを介してオーファンウィンドウを閉じる

4. レジストリエントリをクリーンアップ

これにより、クラッシュまたは終了したエージェントがゾンビブラウザウィンドウを開いたままにすることを防ぎます。

デモ動画 (YouTube)

テストの実行

pytest-asyncioは使用しません。

pip install -e ".[test]"`