Browser Control

BrowserControl

エージェントに視覚で確認できるブラウザーを提供する MCP サーバーです。

_{実際の 1 回のセッションで 12 個のアクションを実行します。仕込みはありません。移動、スクロール、入力、選択、チェック、クリック。番号に注目してください。アクションのたびに最初から描き直されるため、エージェントは毎回番号を読み直します。}

アイデア

ほとんどのブラウザーツールは、モデルに DOM ツリーを渡し、動作するセレクターを記述できることを期待します。 BrowserControl が渡すのは、画像です。

アクションを実行するたびに、インタラクティブな要素の上に番号付きの赤いボックスを描画した新しいスクリーンショットと、同じ要素のテキスト一覧を返します。エージェントは番号で操作します。

click(5)
type_text(3, "hello world")
upload_file(7, "/path/to/resume.pdf")

推測が必要なセレクターも、次のデザイン変更で壊れるセレクターもありません。これは Set of Marks パターンであり、代替手段ではなく、主要なインターフェイスとして使われます。

クイックスタート

uv add browsercontrol      # or: pip install browsercontrol

Chromium は初回実行時に自動でインストールされます。失敗した場合は、 python -m playwright install chromium を一度実行してください。

クライアントから browsercontrol コマンドを指定します。

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

クライアント別のファイルの場所

クライアント	場所
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json（macOS） · ~/.config/Claude/claude_desktop_config.json（Linux） · %APPDATA%\Claude\claude_desktop_config.json（Windows）
Claude Code	claude mcp add browsercontrol -- browsercontrol
Cursor	設定 → Model Context Protocol
Cline	設定 → MCP サーバー
Continue.dev	~/.continue/config.json の mcpServers 配下
Zed	~/.config/zed/settings.json の context_servers 配下に {"command": {"path": "browsercontrol"}} として設定

インストールせずに使いたい場合は、"command": "uvx", "args": ["browsercontrol"] としてください。

クライアントを再起動して、次のように依頼します。

「Hacker News を開いて、トップの記事を教えてください。」

詳しい手順：はじめに。

唯一のルール

要素番号は操作のたびに無効になります。 クリック、入力、スクロール、ページ遷移、スクリーンショットのたびにマップは一から再構築されます。クリック前の要素 7 が、クリック後も要素 7 であることはほとんどありません。

そのため、エージェントは1枚のスクリーンショットをもとに2回クリックする計画を立ててはいけません。操作を行い、新しいスクリーンショットを読み、ターゲットを見つけ直してから、次の操作を行います。デバッグする価値のある失敗のほとんどは、この点に起因します。

ここから、次の2つのことが導かれます。

• 表示領域内にある要素だけがマークされます。 番号がない場合は、たいてい「画面の下の方にある」という意味です。スクロールして、もう一度確認してください。
• クロスオリジンの iframe はマークされません。 オープンシャドウルートと同一オリジンのフレームは走査され、番号が付与されますが、サードパーティの決済フィールドや埋め込みウィジェットには対応できません。これはブラウザーの制約であり、バグではありません。

ツール

7つのカテゴリーにわたる39個のツールがあります。ページに作用するすべてのツールは、注釈付きスクリーンショットと要素マップを返します。

カテゴリー		ツール
ナビゲーション	5	navigate_to go_back go_forward refresh_page scroll
操作	7	click click_at type_text press_key hover scroll_to_element wait
フォーム	3	select_option check_checkbox upload_file
コンテンツ	5	get_page_content get_text get_page_info run_javascript screenshot
タブ	4	create_tab switch_tab close_tab list_tabs
DevTools	11	get_console_logs get_network_requests get_page_errors run_in_console inspect_element get_page_performance get_cookies set_cookie delete_cookie clear_cookies set_viewport
記録	4	start_recording stop_recording take_snapshot list_recordings

名前だけではわかりにくい動作をいくつか紹介します。

• type_text は Playwright の fill() を使います。フィールドに追記するのではなく、置き換えます。
• click はマークの中心にある最前面の要素を特定します。Cookie バナーがターゲットに重なっていると、そのバナーがクリックを受け取ってしまいます。まずオーバーレイを閉じてください。
• upload_file は set_input_files を使うため、ファイル選択ダイアログの操作ではうまくいかないサイトでも動作します。
• screenshot(annotate=True, full_page=True) は クリーンな 画像を返します。ページ全体のキャプチャにはマークを付けられません。
• get_page_content は最大30 KBの Markdown を返します。
• 記録は Playwright のトレースです。npx playwright show-trace ~/.browsercontrol/recordings/<name>.zip で開けます。

エージェントがうまく使えるように教える

サーバーに接続すると、エージェントはどのツールが存在するかを把握できます。同梱の エージェントスキルは、ツールをうまく使う方法を伝えます。 数値は有効期限が切れること、バナーがクリックを妨げること、数値が表示されない場合はスクロールすることなどです。

mkdir -p ~/.claude/skills/browsercontrol
curl -fsSL https://raw.githubusercontent.com/adityasasidhar/browsercontrol/main/skills/browsercontrol/SKILL.md \
  -o ~/.claude/skills/browsercontrol/SKILL.md

ブラウザーを使うタスクでのみ読み込まれるため、それ以外のときに消費するコンテキストは1行だけです。ドキュメントを直接読む場合は、llms.txtから始められます。

設定

環境変数は起動時に一度だけ読み込まれます。

変数	デフォルト
BROWSER_HEADLESS	true	ブラウザーの動作を確認するにはfalseにします
BROWSER_VIEWPORT_WIDTH	1280
BROWSER_VIEWPORT_HEIGHT	720
BROWSER_TIMEOUT	30000	ナビゲーションのタイムアウト（ミリ秒）
BROWSER_USER_DATA_DIR	~/.browsercontrol/user_data	プロファイルディレクトリ
BROWSER_EXTENSION_PATH	—	起動時に読み込む展開済み拡張機能
BROWSER_EXECUTABLE_PATH	—	Playwrightが使用中のプラットフォーム向けのビルドを提供していない場合に操作するChromiumバイナリ
BROWSER_RECORDINGS_DIR	プロファイルの隣	トレースの保存先
BROWSER_SNAPSHOTS_DIR	プロファイルの隣	スナップショットの保存先
LOG_LEVEL	INFO

BROWSER_HEADLESS=false BROWSER_VIEWPORT_WIDTH=390 BROWSER_VIEWPORT_HEIGHT=844 browsercontrol

このツールを選ぶ理由

セッションには実際のChromiumプロファイル（launch_persistent_context）を使用するため、Cookie、localStorage、ログイン状態は再起動後も保持されます。一度ログインすれば、エージェントもログイン状態を保ちます。DevToolsの機能も標準で備えており、コンソール、ネットワークのタイミング、未捕捉の例外、パフォーマンス、計算済みスタイルを、付け足しではなくツールとして利用できます。また、すべてお使いのマシン上で実行されるため、LLM APIキーもクラウドとの通信も、操作ごとのコストもなく、外部にデータが送られることもありません。

率直に言うと、アクセシビリティツリーを使った操作で問題がなければ、Playwright MCPは優れた選択肢です。LLMに操作を計画させたい場合は、StagehandまたはBrowser-Useをご覧ください。BrowserControlの強みは、DevToolsを内蔵した、ビジョンファーストで完全にローカルなブラウザー制御です。詳しい比較についてはドキュメントをご覧ください。

開発

git clone https://github.com/adityasasidhar/browsercontrol
cd browsercontrol
uv sync
uv run playwright install chromium --with-deps

uv run pytest                                  # tests (Playwright is mocked — no real browser)
uv run ruff check . && uv run ruff format .    # lint + format
uv run fastmcp dev browsercontrol/server.py    # dev server with the MCP inspector

browsercontrol/
├── server.py     # FastMCP instance, lifespan, tool registration
├── browser.py    # BrowserManager: Playwright lifecycle, element detection, SoM rendering
├── config.py     # env-var config
└── tools/        # one module per category, each exporting register_*_tools(mcp)

CIでは、Ubuntu、Windows、macOS上でruff、mypy --strict、bandit、pytestを使ってテストスイートを実行します。

コントリビューション

IssueやPRを歓迎します。CONTRIBUTING.mdをご覧ください。新しいツールには、正常系とエラー系の両方のテストを追加してください。既存のtests/test_*.pyファイルに例があります。

取り組む題材をお探しなら、FirefoxとWebKitのサポート、モバイルデバイスのプリセット、ネットワークのモック、スナップショット間のDOM差分、アクセシビリティ監査などがあります。

ライセンス

MITです。FastMCPと Playwrightを基盤として構築されています。