Stealth Browser Mcp

Stealth Browser MCP

MCP 対応 AI エージェント向けのステルスブラウザー自動化です。

nodriver、Chrome DevTools Protocol、FastMCP を活用した Chrome 系ブラウザーの実際のインスタンスを使って、Cloudflare のチャレンジ、ボット対策チェック、ログイン画面を突破します。

スポンサー

NodeMaven — Web スクレイピングと自動化に最適な、業界最高品質の IP を提供する、最も効率的なプロキシプロバイダーです。

NodeMaven を選ぶ理由

• ZIP コードによるターゲティング
• 稼働率 99.9%
• IP フィルタリング：すべてのプロキシの不正利用スコアが 97% 未満
• KYC 不要
• プロキシ帯域幅チェッカー、メタタグチェッカー、IP ルックアップなど、独自の無料ツールを提供

Stealth-browser-mcp ユーザー向け特別コード

• STEALTHMCP35 — モバイルプロキシと住宅用プロキシが 35% オフ
• STEALTHMCP40 — ISP（静的）プロキシが 40% オフ

NodeMaven の利用を開始

スポンサー枠への掲載です。NodeMaven は本プロジェクトの有料スポンサーです。

目次

• スポンサー
• デモ
• 機能
• クイックスタート
• エージェントスキル
• 信頼モデル
• モジュール式アーキテクチャ
• サーバー設定
• ツールボックス
• Stealth と Playwright MCP の比較
• トラブルシューティング
• 使用例
• ショーケース
• ロードマップ
• コントリビューション
• サポート
• ライセンス

デモ

Stealth Browser MCP が Cloudflare のチャレンジを通過し、UI 要素を複製し、AI チャットコマンドを使ってネットワークトラフィックを調査します。

特徴

• ボット対策への耐性 - テストではCloudflareやQueue-It形式のチャレンジを通過しています。結果はサイト、地域、ブラウザーのバージョン、検出器のバージョンによって異なります。
• 11セクションにわたる101個のツール - 基本的なナビゲーションから高度なCDP関数の実行まで対応します。
• モジュール式の読み込み - 101個のツールすべてを実行することも、最小構成の21個のコアツールを実行することもできます。不要なセクションは無効にできます。
• ピクセル単位で正確な要素の複製 - CDPを介して、CSS、DOM構造、イベント、アニメーション、アセットを含む要素全体を抽出します。
• ネットワークの検査 - AI エージェントを通じて、リクエスト、レスポンス、ヘッダー、ペイロード、キャプチャした本文を検査できます。
• 動的フックシステム - 制限付きのPythonフックで、リクエスト／レスポンスのフローを傍受、ブロック、リダイレクト、充足、変更できます。
• CDPの実行 - 信頼されたローカルMCPクライアントを通じて、JavaScript、直接のCDPコマンド、ドキュメント読み込み前のスクリプトを実行できます。
• 即時のテキスト入力 - CDP経由で大量のコンテンツを貼り付けたり、人間らしいキーストロークで入力したり、信頼されたCDPキーイベントで実際のキーを押したりできます。
• クロスプラットフォーム - Windows、macOS、Linux、Docker、CI環境に対応し、ブラウザーとプラットフォームを自動検出します。
• ブラウザーのサポート - Chrome、Chromium、Microsoft Edgeに対応し、実行ファイルを自動検出します。
• シンプルなMCP連携 - カスタムブローカーなしで、標準のMCPクライアントから利用できます。

クイックスタート

1. インストール

Python 3.10以降と、Chrome、Chromium、またはMicrosoft Edgeが必要です。

pipxを使用する場合（推奨）：

pipx install browserstealthmcp

これにより、PATHにstealth-browser-mcpコマンドが追加されます。pipx upgrade browserstealthmcpでアップグレードできます。uvx browserstealthmcpを使うと、インストールせずに実行できます。リリースではなく最新のコミットを実行するには、pipx install git+https://github.com/vibheksoni/stealth-browser-mcp.gitを使用します。

PyPI上のstealth-browser-mcpは別の無関係なプロジェクトに属しているため、PyPIパッケージ名はbrowserstealthmcpです。pipx install stealth-browser-mcpを実行すると、このプロジェクトではなく、その別プロジェクトがインストールされます。

クローンからインストールする場合（開発用）：

git clone https://github.com/vibheksoni/stealth-browser-mcp.git
cd stealth-browser-mcp
python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

pip install -r requirements.txt

2. MCPクライアントに追加する

pipxでインストールした場合：

claude mcp add stealth-browser-mcp -- stealth-browser-mcp

または、任意のクライアントのJSON設定に追加します。

{
  "mcpServers": {
    "stealth-browser-mcp": {
      "command": "stealth-browser-mcp",
      "args": [],
      "env": {}
    }
  }
}

クライアントからコマンドが見つからない場合は、pipx listで表示されるフルパスを使用してください。uvを使う場合は、インストールを省略して"command": "uvx", "args": ["browserstealthmcp"]を使用できます。

Claude Code CLIでクローンから実行する場合：

Windows：

claude mcp add-json stealth-browser-mcp "{\"type\":\"stdio\",\"command\":\"C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe\",\"args\":[\"C:\\path\\to\\stealth-browser-mcp\\src\\server.py\"]}"

macOS / Linux：

claude mcp add-json stealth-browser-mcp '{
  "type": "stdio",
  "command": "/path/to/stealth-browser-mcp/venv/bin/python",
  "args": ["/path/to/stealth-browser-mcp/src/server.py"]
}'

例のパスを、実際のクローンのパスに置き換えてください。

{
  "mcpServers": {
    "stealth-browser-mcp": {
      "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "stealth-browser-mcp": {
      "command": "/path/to/stealth-browser-mcp/venv/bin/python",
      "args": ["/path/to/stealth-browser-mcp/src/server.py"],
      "env": {}
    }
  }
}

pip install fastmcp
fastmcp install claude-desktop src/server.py --with-requirements requirements.txt
fastmcp install claude-code src/server.py --with-requirements requirements.txt
fastmcp install cursor src/server.py --with-requirements requirements.txt

3. 動作を確認する

MCPクライアントを再起動し、エージェントに次のように依頼します。

stealth-browserを使ってhttps://example.comに移動し、スクリーンショットを撮ってください。

エージェントスキル

このリポジトリには、Codex形式のスキルに対応するクライアント向けのエージェントスキルがskills/stealth-browser-mcpに含まれています。推奨されるツールの使用順序、状態の確認、ドキュメント読み込み前のCDPスクリプトの使用方法、ネットワークのデバッグ手順、ブラウザーのクリーンアップに関するルールをエージェントに教えます。

LLMが適切なMCPツールを選べない場合や、操作後にブラウザーの状態を確認し忘れる場合は、このスキルを使用してください。クライアントがリポジトリ内のスキルを自動で読み込まない場合は、skills/stealth-browser-mcpをクライアントのスキルディレクトリに追加するか、シンボリックリンクを作成してください。

信頼モデル

このサーバーは、CDP の実行、ページの JavaScript 実行、Cookie／ストレージへのアクセス、ネットワークインターセプト、動的フック、ヘッダーの変更、ナビゲーション、許可リストに登録されたローカルパスからのファイルアップロードなど、強力なローカルブラウザー制御プリミティブを公開します。

MCP クライアントまたはエージェントをセキュリティプリンシパルとして扱ってください。推奨されるデプロイ方法は、信頼できるデスクトップ MCP クライアントを使用したローカルの stdio トランスポートです。HTTP トランスポートを使用する場合は、STEALTH_BROWSER_MCP_AUTH_TOKEN を設定し、信頼できるローカルネットワークまたはプライベートネットワークの外部に、認証なしの HTTP を公開しないでください。

モジュラーアーキテクチャ

必要な機能だけを選択してください。全 101 ツールのスイートを実行することも、21 ツールのコアに絞ることもできます。

stealth-browser-mcp --minimal
stealth-browser-mcp --disable-cdp-functions --disable-dynamic-hooks
stealth-browser-mcp --list-sections
stealth-browser-mcp --debug
stealth-browser-mcp --transport http --host 127.0.0.1 --port 8000

クローンから実行する場合も、python src/server.py に同じフラグを指定できます。

詳細なサーバー診断を stderr に出力するには、--debug を使用するか、STEALTH_BROWSER_DEBUG=1 を設定してください。JSON-RPC トランスポートの出力が破損するのを防ぐため、通常の MCP stdio 実行ではデフォルトで出力は抑制されます。

利用可能なセクション：

サーバー設定

これらは MCP サーバープロセスの環境変数です。シェル、サービスマネージャー、Docker 環境、または MCP クライアントの env ブロックで設定してください。

PowerShell の例：

$env:STEALTH_BROWSER_MCP_AUTH_TOKEN='replace-with-a-long-random-token'
$env:BROWSER_IDLE_TIMEOUT='900'
$env:BROWSER_IDLE_REAPER_INTERVAL='30'
$env:BROWSER_ORPHAN_PROFILE_MAX_AGE='43200'
$env:BROWSER_FILE_UPLOAD_ALLOWED_DIRS='C:\Users\me\uploads;C:\Users\me\Documents'
python src/server.py

MCP クライアントの env ブロック：

{
  "mcpServers": {
    "stealth-browser-mcp": {
      "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py"],
      "env": {
        "STEALTH_BROWSER_MCP_AUTH_TOKEN": "replace-with-a-long-random-token",
        "BROWSER_IDLE_TIMEOUT": "900",
        "BROWSER_FILE_UPLOAD_ALLOWED_DIRS": "C:\\Users\\me\\uploads;C:\\Users\\me\\Documents"
      }
    }
  }
}

HTTP クライアントの例：

from fastmcp import Client
from fastmcp.client.auth import BearerAuth

client = Client(
    "http://127.0.0.1:8000/mcp/",
    auth=BearerAuth("replace-with-a-long-random-token"),
)

インスタンスごとのアイドルタイムアウトの上書き：

• spawn_browser(idle_timeout_seconds=1800) は、そのインスタンスを操作のない状態で 30 分間維持します。
• spawn_browser(idle_timeout_seconds=0) は、そのインスタンスのアイドルクリーンアップを無効にします。

ツールボックス

Stealth と Playwright MCP の比較

検出結果は特定時点のものであり、サイトのポリシー、地域、ブラウザーのバージョン、IP の評価、検出器のバージョンによって異なります。Linux、Windows、macOS 上で GitHub Actions により実行される benchmarks/stealth/ のベンチマークから得られた週次の自動テスト結果と、以前の手動スナップショットについては、STEALTH_TESTS.md をご覧ください。

トラブルシューティング

互換性のあるブラウザーが見つからない Chrome、Chromium、または Microsoft Edge をインストールしてください。サーバーは利用可能な最初のブラウザーを自動検出します。診断には validate_browser_environment_tool() を実行してください。

ツールがハングする、または不正な JSON を返す MCP の stdio トランスポートでは、デバッグ出力を stdout に出力しないでください。最新の master ブランチを取得し、問題を診断する場合を除いてデバッグログを無効にしてください。

通常の実行を煩雑にせず、詳細な診断情報が必要 python src/server.py --debug を使用するか、STEALTH_BROWSER_DEBUG=1 を設定してください。デバッグログは stderr に出力されます。通常の MCP stdio 実行では、デフォルトで出力は抑制されます。

Linux、Docker、または CI でブラウザーがクラッシュする 環境で必要な場合に限り --sandbox=false を指定して実行するか、環境が Chromium のサンドボックスに対応していることを確認してください。サーバーは root／コンテナー環境を自動検出し、起動引数を調整します。

孤立した Chromium プロセスや uc_* の一時プロファイルが蓄積する サーバーはアイドル状態のブラウザーインスタンスを自動的に終了し、追跡対象の孤立プロセスと古い uc_* 一時プロファイルを起動時にクリーンアップします。ブラウザーのライフサイクルを完全に手動で管理する場合に限り、BROWSER_IDLE_TIMEOUT=0 を設定してください。

macOS のディスクが code_sign_clone フォルダーでいっぱいになる 以前のバージョンでは、Chrome が起動のたびにアプリバンドルを com.google.Chrome.code_sign_clone にコピーし、インスタンスがクラッシュまたは強制終了された場合も、そのコピーが残っていました。現在、サーバーは MacAppCodeSignClone を無効にして Chrome を起動するため、新しいコピーは作成されません。以前のバージョンで残されたコピーを削除するには、Chrome を終了して rm -rf /private/var/folders/*/*/X/com.google.Chrome.code_sign_clone を実行してください（Edge の場合は com.microsoft.edgemac.code_sign_clone を使用します）。

AI チャットにツールが多すぎて煩雑になる コアツール 20 個を使うには --minimal、xpool 互換の動作には --xpool-safe を使用するか、次のようにセクションを選択して無効にしてください。

python src/server.py --disable-cdp-functions --disable-dynamic-hooks --disable-progressive-cloning

モジュールが見つからないというエラーが発生する 仮想環境を有効化し、依存関係をインストールしたことを確認してください。

pip install -r requirements.txt

使用例

• 市場調査 - 競合他社の価格と機能を抽出し、比較表を出力します。
• UI の複製 - 正確なフォント、スタイル、アセット、インタラクションを備えた価格セクションを再現します。
• 在庫の監視 - 商品ページを監視し、在庫状況が変わったときに通知します。
• API のリバースエンジニアリング - リクエストをインターセプトし、エンドポイントを整理して、データフローを調査します。
• フォームの自動化 - 許可リストに登録されたパスからファイルをアップロードし、処理後のページ状態を確認します。

すべて単一の AI エージェントとの会話から実行できます。

ショーケース

Augment Codeのヒーローセクションのクローン - ユーザーがClaudeに、augmentcode.comのヒーローセクションをクローンするよう依頼しました。エージェントはステルスブラウザーを起動してサイトにアクセスし、CDP経由で要素全体（スタイル、構造、アセット）を抽出して、レスポンシブデザインとアニメーションを備えた、ピクセル単位で正確なHTMLを生成しました。会話全体にかかった時間は2分未満でした。

再現例を見る | 全手順を見る

ロードマップ

ROADMAP.mdで最新の計画をご確認ください。コントリビューションを歓迎します。

コントリビューション

CONTRIBUTING.mdを読み、PRを作成してください。初めてのコントリビューターも歓迎します。

このプロジェクトで時間を節約できたら、リポジトリにスターを付けてください。想像以上に役立ちます。

サポート

このツールで時間を節約できた、または収益を得られた場合は、開発へのご支援をご検討ください。

• コーヒーをおごる

ライセンス

MIT - 詳細はLICENSEをご覧ください。