stealth-browser-mcp

AIアシスタントに、ログイン状態を維持した本物のChromeブラウザを提供するMCPサーバーです。

ほとんどのブラウザ自動化ツールは、モデルにまっさらな新しいブラウザを渡します。このツールは永続的なChromeプロファイルを操作するため、2FA、CAPTCHA、デバイス承認など、サイトが要求するあらゆる認証を自分で一度済ませてしまえば、モデルは以降の実行でそのセッションを使い続けることができ、パスワードを目にすることはありません。

スクリプトによるログインを許さないサイトのために、2つの逃げ道を用意しています。入力時にmacOSキーチェーンから取得する認証情報と、Chromeの仮想オーセンティケーターで再生するWebAuthnパスキーです。

[!WARNING] これは強力なツールです。言語モデルに、あなたのライブセッションを保持したブラウザの制御を委ねることになり、モデルが選んだページに保存済みパスワードを入力することも可能です。大切なものを相手にする前に、SECURITY.mdと責任ある利用をお読みください。

目次

• 仕組み

• 要件

• インストール

• MCPクライアントに接続する

• 最初のログイン

• ツールリファレンス

• キーチェーンに認証情報を保存する

• パスキー

• 設定

• ステルス性の検証

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

• 責任ある利用

• ライセンス

Related MCP server: agent-browser-mcp

仕組み

        MCP client (Claude Code, Claude Desktop, Cursor, …)
                          │
                          │  JSON-RPC over stdio
                          ▼
              ┌───────────────────────────┐
              │   stealth-browser-mcp     │
              │   16 tools, one browser   │
              └─────┬───────────────┬─────┘
                    │               │
     credentials    │               │   CDP + Puppeteer
                    ▼               ▼
        ┌───────────────────┐   ┌───────────────────────┐
        │  macOS Keychain   │   │  Google Chrome        │
        │  stealth-mcp:*    │   │  + stealth plugin     │
        │  passwords,       │   │  + WebAuthn virtual   │
        │  passkey material │   │    authenticator      │
        └───────────────────┘   └───────────┬───────────┘
                                            │
                                            ▼
                              ┌─────────────────────────┐
                              │  Persistent profile dir │
                              │  cookies · localStorage │
                              │  IndexedDB · sessions   │
                              └─────────────────────────┘

3つの要素が機能を支えています。

永続性。 Chromeは使い捨てではなく固定のuserDataDirに対して起動されます。一度対話的にログインすれば、Cookieは以降のすべての実行で保持されます。実際のサイトで自動化が失敗する一般的な原因がなくなります。

ステルス性。 puppeteer-extra-plugin-stealthが既知の自動化検出シグナルを修正し、サーバー側でもさらにいくつかの対策を重ねます。navigator.webdriverはundefinedになり、window.chrome.runtimeは存在し、ユーザーエージェントからHeadlessChromeが除去され、--disable-blink-features=AutomationControlledが設定されます。クリックはマウスをターゲット内部のジッター付きの点までパスに沿って移動させてから押下します。タイピングは30〜100msの間隔で1文字ずつ行われます。

セッションの作成ではなくセッションの再利用。 設計目標はログインの自動化を避けることです。キーチェーン自動入力とパスキー再生は、それができない場合のために存在します。

要件

• Node.js 18以降

• Google Chrome。 Puppeteer同梱のChromiumでも動作しますが、実際のChromeビルドの方が検出されにくいです。

• macOS（キーチェーンとパスキー機能を使う場合）。ナビゲーション、抽出、スクリーンショット、永続プロファイルなど、その他すべてはクロスプラットフォームです。キーチェーン層は/usr/bin/securityを外部コマンドとして呼び出すため、他のプラットフォームでは失敗します。ブラウザツールはこれに触れません。

インストール

git clone https://github.com/lauyuen/stealth-browser-mcp.git
cd stealth-browser-mcp
npm install

必要に応じて、サンプルの環境ファイルをコピーして編集します。

cp .env.example .env

ブラウザが起動し、回避策が有効になっていることを確認します。

npm run check-stealth

MCPクライアントに接続する

サーバーはstdioで通信します。絶対パスでsrc/server.jsをクライアントに指定してください。

Claude Code

claude mcp add stealth-browser -- node /absolute/path/to/stealth-browser-mcp/src/server.js

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"]
    }
  }
}

その他のMCPクライアント — 同じ形式に加えて、オプションでプロファイルの上書きが可能です。

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"],
      "env": {
        "BROWSER_PROFILE_DIR": "/absolute/path/to/a/private/profile/dir"
      }
    }
  }
}

その後、クライアントを再起動してください。browser_statusが接続確認の最も手軽な方法です。

最初のログイン

モデルがサイトを使う前に、自分でプロファイルを初期化します。

npm run login -- https://example.com

MCPサーバーが使用するのと同じプロファイルで、表示されたChromeウィンドウが開きます。通常どおりログインしてください。パスワードマネージャー、2FAプロンプト、CAPTCHA、「このデバイスを記憶する」など、すべての手順を実行します。完了したらターミナルでEnterを押すと、セッションがディスクにフラッシュされます。

以降のMCP実行はすべてそのセッションを引き継ぎます。サイトごとに繰り返してください。セッションはサイト側のスケジュールで期限切れになるため、サイトからログアウトされたらこの手順を再実行してください。

ツールリファレンス

ナビゲーションと操作

ページの読み取り

セッションと認証

ブラウザのライフサイクル

ブラウザはデフォルトでヘッドレスで起動し、呼び出し間で再利用されます。 browser_open_interactive_windowは、表示ウィンドウに切り替える唯一のツールです。

キーチェーンに認証情報を保存する

パスワードはmacOSキーチェーンのstealth-mcp:サービスプレフィックスの下に保存されます。このリポジトリ内のファイルにも、モデルのコンテキストにも保存されることはありません。

npm run keychain set github you@example.com     # prompts; input is not echoed
npm run keychain get github you@example.com     # confirms presence, prints length only
npm run keychain delete github you@example.com

モデルはシークレットを知ることなくログインを実行します。

// browser_autofill_login
{
  "service": "github",
  "account": "you@example.com",
  "usernameSelector": "#login_field",
  "passwordSelector": "#password",
  "submitSelector": "input[type='submit']"
}

serviceは任意のラベルです。CLIとツール呼び出しの間で一致していれば何でも構いません。

スクリプト用にパスワードを末尾のCLI引数として渡すこともできますが、シェル履歴とプロセスリストに残るため、その場合はコマンドが警告を表示します。

パスキー

ChromeはDevTools Protocol経由でWebAuthn仮想オーセンティケーターを公開しています。これはWebAuthnフローをテストするためのソフトウェアオーセンティケーターです。このサーバーはそれを操作し、結果の鍵素材をキーチェーンに永続化して、実行間で保持されるようにします。

自動化用パスキーの登録

1. 引数なしでpasskey_enable_virtual_authenticatorを実行します。

2. サイトの「パスキーを追加」フローに移動して完了します。仮想オーセンティケーターがチャレンジに応答するため、OSのプロンプトは表示されません。

3. サイトのrpIdとアカウントを指定してpasskey_save_registrationを実行します。

後で使用する

rpIdとaccountを指定してpasskey_enable_virtual_authenticatorを実行すると、ナビゲーション前に保存済みの認証情報が注入され、サイトはプロンプトなしでサインインさせます。

[!CAUTION] この方法で保持されるパスキーはファイルであり、ハードウェアキーではありません。コピーが可能で、これはまさに本物のパスキーが防ごうとしている性質です。自動化専用のパスキーの登録にのみ使用してください。メール、銀行、その他失ったら困るものを守るパスキーには使用しないでください。

設定

すべての設定は環境変数で、プロセス環境または.envファイルから読み取られます。.env.exampleを参照してください。

Chromeの起動フラグとデフォルトの1280×800ビューポートはsrc/config.jsにあります。いくつかのフラグはセキュリティと互換性をトレードオフしています。SECURITY.mdで、どのフラグがなぜ削除すべきかもしれないかを説明しています。

ステルス性の検証

npm run check-stealth

navigator.webdriver、window.chrome、window.chrome.runtime、プラグイン数、navigator.languages、および有効なユーザーエージェントを報告し、解決されたプロファイルとChromeのパスを出力します。

より厳密なチェックを行うには、browser_navigate の後に browser_screenshot を実行し、ブラウザをフィンガープリンティングページ（例：bot.sannysoft.com や abrahamjuliot.github.io/creepjs）に向けてください。

完全に検出を逃れられるステルス設定は存在しません。防御の堅いサイトはフィンガープリンティングと行動分析、IPレピュテーション、アカウント履歴を組み合わせており、自動化を見抜きます。これは「明らかなチェックを引っかけない」という意味であり、「不可視」という意味ではありません。

トラブルシューティング

「Failed to launch the browser process」/ プロファイルがロックされている。 Chromeはプロファイルディレクトリごとに1つのプロセスしか許可しません。同じディレクトリに対して手動で起動したChromeがあれば閉じてください。サーバーは起動時に古いSingleton*ロックファイルをクリアし、DevToolsポート経由で稼働中のインスタンスに再接続しますが、プロファイルを所有している実行中のChromeが優先されます。

サイトがモデルをログアウトさせる、またはブロックする。 保存されたセッションが期限切れです。npm run login -- <url> を再実行してください。

セレクタが一致しない。 狭いセレクタで browser_extract_html を呼び出し、推測する代わりにモデルに実際のマークアップを読ませてください。シングルページアプリケーションでは入力要素のマウントが遅れることがよくあるため、先に browser_wait_for を使用してください。

CAPTCHAが表示される。 browser_open_interactive_window を呼び出して自分で解決し、続行してください。解決済みの状態はプロファイルに保持されます。

LinuxまたはWindowsでキーチェーンエラーが発生する。 これは想定内です。そのレイヤーはmacOS専用です。ブラウザツールはどこでも動作しますが、認証情報ツールとパスキーツールは動作しません。

責任ある利用

このプロジェクトの目的は、アシスタントがあなたがすでにアカウントを持っているサイトで、あなた自身が確立したセッションを使用して動作できるようにすることです。それが意図された範囲であり、永続プロファイルの設計もそれを反映しています。

検出回避と認証情報の自動化は、明らかに他の目的に転用できます。サイトに対して実行する前に、以下を考慮してください：

• サイトの利用規約。 多くのサイトは自動アクセスを明示的に禁止しています。ボット防御を回避することは、あなたが同意した契約違反になる可能性があり、一部の法域では不正アクセスが刑事責任を伴います。制御を回避できることは、それを実行する許可にはなりません。

• 同意。 自分が所有するアカウント、または書面による権限を得て操作するアカウントのみを自動化してください。キーチェーンにある他人の認証情報は同意ではありません。

• 負荷。 レート制限を守ってください。該当する場合は robots.txt を尊重してください。サイトに実際のコストをかける自動化は、その手法が全員に対して禁止される良い方法です。

• 他人のデータ。 モデルが読み取るページは、MCPクライアントのプロバイダーに流れます。第三者の個人情報をそこに通さないでください。

特定のサイトの保護を無効化すること、認証情報の収集、または悪用の拡大を主目的とするコントリビューションはマージされません。

ライセンス

MIT © Yuen Lau