SeleniumBase MCP サーバー

SeleniumBase のブラウザ自動化をツールとして公開し、 Model Context Protocol を通じて、あらゆる MCP クライアント（Claude Desktop、Claude Code など）が実際のブラウザを操作できるようにします。

このフォルダには 3つのサーバーバリアント があります：

3つともデフォルトは headless=False — セッション開始時に headless=True を 渡さない限り、ブラウザウィンドウは表示されます。

タスクに合った *_server.py を MCP クライアント設定で指定してください（下記 手順3を参照）— または、3つすべてを異なる名前で登録することもできます。

1. インストール

（Python 3.10+ と uv が必要です）

git clone https://github.com/seleniumbase/seleniumbase-mcp.git
cd seleniumbase-mcp
uv sync

uv sync は pyproject.toml を読み取り、このフォルダ内に .venv/ を作成し、 2つの依存関係（mcp[cli]、seleniumbase）とこのプロジェクト自体を インストールします — これにより、[project.scripts] 経由で3つのコンソールスクリプト コマンドが登録されます：

• seleniumbase-driver

• seleniumbase-cdp

• seleniumbase-sb

各コマンドは、そのサーバーファイルの main() 関数 （mcp.run(transport="stdio")）を呼び出すだけです。これにより、MCP クライアント コマンドとして uv run <name> を — python パスも venv パスもスクリプトパスも 指定せずに — 使用できます（下記手順3および4を参照）。

# SeleniumBase's Driver() and SB() formats need a browser driver downloaded:
uv run seleniumbase get chromedriver
# (Not needed for the "seleniumbase-cdp" Pure CDP Mode MCP Server,
#  which doesn't use WebDriver at all.)

（uv がない場合？通常の python3 -m venv venv && pip install -e . でも機能します — 以下のすべてで uv run <name> の代わりに python <script>.py を使用し、 MCP クライアント設定ではパスフリーのオプションではなく、絶対パスの venv/bin/python + スクリプトパスを使用してください。）

Related MCP server: gotham-browser

2. スタンドアロンで試す（任意の動作確認）

uv run mcp dev cdp_server.py

これにより、SeleniumBase の「ピュアCDPモード」MCP サーバー用の MCP Inspector が開き、 コマンド（「ツール」）をテストできます。終了するには Ctrl+C を押します。 実際のテストは、クライアントへの配線です（次のステップ）。

3. Claude Desktop に接続する

Claude Desktop は「プロジェクト」ディレクトリから実行されるわけではないため、 素の uv run <name> ではこのリポジトリが見つかるとは限りません。安定した 設定を行うには2つの方法があります：

オプション A — グローバルインストール（推奨、どこにもパス不要）：

uv tool install .          # from inside the repo, installs the 3 commands globally

これにより、seleniumbase-driver/seleniumbase-cdp/seleniumbase-sb が PATH に恒久的に追加されます（bin ディレクトリが PATH にないと警告された場合は、 uv tool ensurepath を一度実行してください）。その後、claude_desktop_config.json は 次のようになります：

{
  "mcpServers": {
    "seleniumbase-cdp": { "command": "seleniumbase-cdp" },
    "seleniumbase-driver": { "command": "seleniumbase-driver" },
    "seleniumbase-sb": { "command": "seleniumbase-sb" }
  }
}

オプション B — uv をリポジトリに直接指定する（絶対パス1つで済みますが、 venv/interpreter パスを追跡する必要はなく、追加インストールも不要）：

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-sb"]
    }
  }
}

claude_desktop_config.json の場所はシステムによって異なります：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop を再起動すると、🔨 ツールアイコンが表示され、サーバーが 接続されたことがわかります。start_browser、navigate、click などの ツールが利用可能になります。実際に必要なエントリだけを残してください — ブラウザ自動化サーバーが3つもあるのは、1つだけで十分な場合には多すぎます。

4. Claude Code に接続する

このリポジトリの .mcp.json はチェックイン済みで、そのまま使用できます — uv run <name> が pyproject.toml からこのプロジェクトを解決するため、 パスの編集は不要です：

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-sb"]
    }
  }
}

Claude Code は、claude を起動したディレクトリから .mcp.json を自動的に 読み込みます。このリポジトリ（またはそのクローン）内から claude を実行する限り、 そのまま機能します — リポジトリをクローンするすべてのチームメイトにとって、 マシン固有の編集なしで同じように動作します。

.mcp.json に頼らずにサーバーを手動で登録したい場合は：

claude mcp add seleniumbase-cdp -- uv run seleniumbase-cdp
claude mcp add seleniumbase-driver -- uv run seleniumbase-driver
claude mcp add seleniumbase-sb -- uv run seleniumbase-sb

（リポジトリディレクトリ内から実行してください。理由は上記と同じです。）

公開されているツール（driver_server.py）

設計上の注意点 / ユースケースに合わせて調整すべき点

• 単一のグローバルセッション。 各サーバーは一度に1つのブラウザセッションを保持します。 これは、MCP サーバーが通常（クライアント接続ごとに1プロセス）起動される方法と一致し、 ツールサーフェスをシンプルに保ちます。複数の同時ブラウザタブ/セッションが必要な場合は、 名前付きセッションの dict に拡張し、各ツールに session_id パラメータを追加することになります。

• ブロッキング呼び出し。 SeleniumBase の呼び出しは同期であり、ページの読み込みや 要素の待機中はサーバーをブロックします。単一ユーザーのローカルツールでは問題ありませんが、 マルチクライアントサーバーの場合は、asyncio.to_thread 経由のスレッドプールで 実行することを検討してください。

• ヘッドレス vs ヘッド付き。 デフォルトはヘッド付き（headless=False）で、 ブラウザの動作を確認でき、ヘッドレス Chrome をブロックするサイトでも機能します。 フローを確認したら、バックグラウンド/サーバー用途では headless=True を渡してください。 sb_server.py の uc=True（undetected-chromedriver）は、ボット対策の壁に対する 防御にも役立ちます。

拡張

ツールを追加するには、対応する SeleniumBase メソッドを呼び出す @mcp.tool() デコレータ付き関数を追加するだけです — SeleniumBase には、 ファイルアップロード、ホバー、アラート、ネットワーク状態など、 上記でまだラップされていないメソッドが多数あります。

cdp_server.py — ピュアCDPモード

seleniumbase.sb_cdp.Chrome をラップします。これは SeleniumBase の最もステルス性の高い モードです：ブラウザは Chrome DevTools Protocol 経由でのみ駆動され、WebDriver は 一切関与しません。リファレンス： cdp_mode_methods.md。

ツールグループ

CDP 固有の設計上の注意点

• 要素はハンドルとしてワイヤを渡ることはありません。 ネイティブCDPモードでは、find_element() は独自のメソッド（例: el.click()、el.get_html()）を持つライブオブジェクトを返します。MCPツールはJSONシリアライズ可能なデータしか返せないため、find_element_info/find_all_info は要素を後でメソッドを呼び出せるハンドルとして返す代わりに、プレーンなdict（tag_name、text、html）へと即座に解決します。複数の候補からどれか1つを操作する必要がある場合は、「検索してからクリック」を2つの別々のステップとして行うのではなく、click_nth_element（位置指定で操作）を使用してください。

• CAPTCHA解決は万能ではありません。 solve_captcha は対応しているチャレンジタイプ（例: SeleniumBaseデモアプリのCloudflare Turnstile）を処理しますが、任意のCAPTCHAを確実に回避するものではありません。

• セッションの終了処理。 sb.quit()（close_browser によって使用）はセッションを終了する文書化された方法です。プロセスが sb.quit() を呼び出さずに終了した場合も、ブラウザは自動的に閉じます。

• ラップしていないもの: PyAutoGUIベースの gui_* メソッド（設計上除外 — 上位レベルの設計ノート参照）、低レベルの内部処理（get_websocket_url、add_handler、権限付与、生の get_document/get_flattened_document）、およびメソッドの正確なエイリアス（open/goto vs get）は、ツールリストを焦点を絞って保つために省略されています。必要であれば、他のツールと同様に追加してください。

sb_server.py — with文なしのSB()

seleniumbase.SB()（通常はコンテキストマネージャとして使用）をラップします：

with SB(uc=True) as sb:
    sb.goto(...)

MCPサーバーのツール呼び出しは、別々の関数呼び出しにまたがって一度に1回ずつ行われるため、with で囲む単一のインデントブロックは存在しません。そこでこのサーバーでは、コンテキストマネージャプロトコルを手動で呼び出しています：

sb_context = SB(**kwargs)
sb = sb_context.__enter__()   # in start_browser
...
sb_context.__exit__(None, None, None)   # in close_browser

sb は BaseCase インスタンスであり、SeleniumBaseで最も広範なAPIです。driver_server.py 内の Driver が公開する機能のスーパーセットであり、UCモードのステルスヘルパーや、driver_server.py/cdp_server.py にはないいくつかの追加機能も含みます。このサーバーは、既にカバーされているすべてを再ラップするのではなく、それらの追加機能に焦点を当てます：

さらに、このサーバーは、他の2つのサーバーと同じコアのナビゲーション/インタラクション/待機/アサーション/クッキー/スクロール/タブ/出力ツールを備えています。これらは Driver やCDPのメソッド名ではなく、BaseCase のメソッド名（例: sb.goto、sb.click、sb.assert_element）を介して呼び出します。

SB() 固有の設計ノート

• UCモード（ステルスモード）には起動時に uc=True が必要です。 必要な場合は、あらかじめ start_browser に uc=True を渡してください。

• activate_cdp_mode は新しいセッションを開始しません。 既存の sb セッションの背後のモードを、以降のアクションのためにPure CDPへ切り替えます。これはフロー途中でのエスカレーションであり、新しいブラウザを起動するものではありません。