Browsercontrol

🚀 BrowserControl

BrowserControl は、AIエージェントにブラウザの完全なアクセス権を与えるMCPサーバーです。ビジョンファーストなアプローチを採用しており、CSSセレクタやXPathを必要とせず、単に番号を指定するだけでウェブサイトとの対話が可能です。

🚀 クイックスタート

インストール

# pipを使用する場合
pip install browsercontrol

# uvを使用する場合（高速インストールを推奨）
uv add browsercontrol

# 初回実行時にChromiumが自動インストールされます。追加の手順は必要ありません！

サーバーの起動

# CLIを使用する場合
browsercontrol

# Pythonモジュールとして実行する場合
python -m browsercontrol

# FastMCPを使用する場合
fastmcp run browsercontrol.server:mcp

AIエージェントへの接続

BrowserControlは、MCP互換のAIエージェントまたはIDEと連携します。使用するプラットフォームを選択してください。

{
  "mcpServers": {
    "browsercontrol": {
      "command": "browsercontrol"
    }
  }
}

# MCP設定をセットアップする
export MCP_SERVERS='{"browsercontrol": {"command": "browsercontrol"}}'

# またはGeminiの設定ファイルに追加する

{
  "browsercontrol": {
    "command": "browsercontrol"
  }
}

{
  "mcpServers": [
    {
      "name": "browsercontrol",
      "command": "browsercontrol"
    }
  ]
}

{
  "browsercontrol": {
    "command": "browsercontrol"
  }
}

{
  "context_servers": {
    "browsercontrol": {
      "command": {
        "path": "browsercontrol"
      }
    }
  }
}

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# BrowserControlに接続する
server_params = StdioServerParameters(
    command="browsercontrol",
    args=[],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # 初期化
        await session.initialize()

        # 利用可能なツールをリストする
        tools = await session.list_tools()

        # ツールを呼び出す
        result = await session.call_tool("navigate_to", {
            "url": "https://github.com"
        })

{
  "mcpServers": {
    "browsercontrol": {
      "command": "uvx",
      "args": ["browsercontrol"]
    }
  }
}

{
  "mcpServers": {
    "browsercontrol": {
      "command": "pipx",
      "args": ["run", "browsercontrol"]
    }
  }
}

{
  "mcpServers": {
    "browsercontrol": {
      "command": "browsercontrol",
      "env": {
        "BROWSER_HEADLESS": "false",
        "BROWSER_VIEWPORT_WIDTH": "1920",
        "BROWSER_VIEWPORT_HEIGHT": "1080",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

✨ 主な機能

このツールの特徴

マークセット（SoM）の秘密

すべてのスクリーンショットには、対話型要素に番号付きの赤いボックスが付けられています。

Found 15 interactive elements:
  [1] button - Sign In
  [2] input - Search...
  [3] a - Products
  [4] a - Pricing
  [5] button - Get Started

エージェントはこれらの番号を見て、click(1) を呼び出すだけでサインインできます。CSSセレクタやXPath、推測は必要ありません。

主な利点

1. マルチタブオーケストレーション：新しいウィンドウが開いても迷うことなく、list_tabs() で開いているすべてのページ、タイトル、URLを確認でき、switch_tab(index) で異なるサイト間でマルチタスクが可能で、create_tab(url) で参照や並列ワークフローを開くことができます。
2. セッションとクッキー管理：ログインフォームの問題を解決し、set_cookie() で認証トークンを注入してすぐにログインでき、get_cookies() でセッションの問題をデバッグまたは状態をエクスポートでき、clear_cookies() でプロファイル全体をクリアすることなく新しいスタートができます。
3. 信頼性の高いファイルアップロード：ほとんどのAIエージェントが <input type="file"> に遭遇すると失敗しますが、BrowserControlはネイティブのブラウザエンジンフックを使用して upload_file(id, path) でボタンとローカルファイルを指定するだけでアップロードできます。
4. 開発者ツールセット：他のツールでは提供されないツールを使用してプロのようにデバッグできます。

get_console_logs()      # ブラウザのエラーを確認する
get_network_requests()  # API呼び出しを監視する
get_page_errors()       # JavaScriptの例外をキャッチする
run_in_console(code)    # リアルタイムでデバッグする
inspect_element(5)      # 計算されたスタイルを取得する
get_page_performance()  # コアウェブバイタルを取得する

5. セッション記録：start_recording() で記録を開始し、ブラウジングを行って stop_recording() で記録を保存します。保存された記録はPlaywrightトレースビューアで表示できます。

start_recording()  →  Browse around  →  stop_recording()
                                              ↓
                               session_20260202.zip
                         (View with Playwright trace viewer)

6. 動的ビューポート制御：set_viewport(width, height) で再起動することなく解像度を変更し、レスポンシブデザインのテストやモバイル画面のエミュレーションができます。
7. 真の永続性：クッキー、localStorage、セッショントークン、ログイン状態、ブラウザ履歴が永続化され、一度ログインするとセッション間でログイン状態が維持されます。 | 維持される項目 | BrowserControl | 他のツール | | ---- | ---- | ---- | | クッキー | ✅ | ❌ | | localStorage | ✅ | ❌ | | セッショントークン | ✅ | ❌ | | ログイン状態 | ✅ | ❌ | | ブラウザ履歴 | ✅ | ❌ |

📦 インストール

# pipを使用する場合
pip install browsercontrol

# uvを使用する場合（高速インストールを推奨）
uv add browsercontrol

# 初回実行時にChromiumが自動インストールされます。追加の手順は必要ありません！

💻 使用例

ウェブリサーチ

You: "Go to Wikipedia and find out when Python was created"

Claude: *navigates to wikipedia.org*
        *types "Python programming language" in search*
        *clicks search result*
        *reads the page*

        "Python was created by Guido van Rossum and first released in 1991."

ウェブアプリのデバッグ

You: "Go to my app at localhost:3000 and check for any errors"

Claude: *navigates to localhost:3000*
        *calls get_console_logs()*

        "I found 2 errors:
         [ERROR] Uncaught TypeError: Cannot read property 'map' of undefined
         [ERROR] Failed to load resource: 404 /api/users"

        *calls get_network_requests()*

        "The /api/users endpoint returned 404. Check your API route."

記録付きの自動テスト

You: "Test the login flow on my site. Start recording."

Claude: *calls start_recording()*
        *navigates to site*
        *types email in element 3*
        *types password in element 4*
        *clicks Login button (element 5)*
        *verifies successful redirect*
        *calls stop_recording()*

        "Login test passed! Recording saved to session_20260202.zip"

フォーム自動化

You: "Fill out the contact form on example.com"

Claude: *navigates to example.com/contact*
        *types name in element 2*
        *types email in element 3*
        *types message in element 4*
        *clicks Submit (element 5)*

        "Form submitted successfully!"

📚 詳細ドキュメント

利用可能なツール

ナビゲーション

インタラクション

タブ管理

フォーム

コンテンツ抽出

開発者ツール

記録

設定

環境変数を使用して設定できます。

例:

# 可視ブラウザで実行する（デバッグ用）
BROWSER_HEADLESS=false browsercontrol

# モバイルビューポートのエミュレーション
BROWSER_VIEWPORT_WIDTH=375 BROWSER_VIEWPORT_HEIGHT=812 browsercontrol

# 詳細ログ
LOG_LEVEL=DEBUG browsercontrol

🔧 技術詳細

アーキテクチャ

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│   AI Agent      │────▶│  BrowserControl  │────▶│   Browser   │
│ (Claude/Gemini) │◀────│   MCP Server     │◀────│ (Chromium)  │
└─────────────────┘     └──────────────────┘     └─────────────┘
        │                        │                      │
        │   "click(5)"           │   mouse.click()      │
        │◀───────────────────────│◀─────────────────────│
        │   [annotated           │   [screenshot +      │
        │    screenshot]         │    element map]      │

動作原理

1. AIがコマンドを送信する — click(5)
2. サーバーが要素を見つける — 最後のスクリーンショットから要素 #5 を検索する
3. ブラウザがアクションを実行する — 要素の座標でクリックする
4. 状態をキャプチャする — 新しいスクリーンショットを撮り、要素を検出する
5. アノテーションを付ける — 対話型要素に番号付きのボックスを描画する
6. AIに返す — アノテーション付きの画像と要素リストを送信する

プロジェクト構造

browsercontrol/
├── __init__.py          # パッケージエクスポート
├── __main__.py          # CLIエントリポイント
├── server.py            # MCPサーバーのセットアップ
├── browser.py           # SoM付きのBrowserManager
├── config.py            # 環境設定
└── tools/
    ├── navigation.py    # ナビゲーションツール
    ├── interaction.py   # クリック、入力、ホバーツール
    ├── forms.py         # フォーム処理ツール
    ├── content.py       # コンテンツ抽出ツール
    ├── devtools.py      # 開発者ツール
    ├── recording.py     # セッション記録ツール
    └── tabs.py          # タブ管理ツール

📄 ライセンス

MITライセンス — 自由に使用できます。

🤝 コントリビューション

コントリビューションは大歓迎です！詳細については、コントリビューションガイドを参照してください。

コントリビューションのアイデア:

• [ ] Firefox/WebKitサポート
• [ ] DOM差分検出（変更を検出する）
• [ ] アクセシビリティ監査ツール
• [ ] モバイルエミュレーションプリセット
• [ ] クッキーのインポート/エクスポートファイル

# クローンしてインストール
git clone https://github.com/adityasasidhar/browsercontrol
cd browsercontrol
uv sync

# テストを実行
uv run pytest

# 開発モードで実行
uv run fastmcp dev browsercontrol/server.py

🔧 トラブルシューティング

xvfb-run browsercontrol

python -m playwright install chromium

ls -la ~/.browsercontrol/

pkill -f browsercontrol
browsercontrol

npx playwright show-trace ~/.browsercontrol/recordings/session.zip

ウェブを見る必要のあるAIエージェント向けに構築されました。

⭐ GitHubでスターをつける • 🐛 バグを報告する • 💡 機能要求をする