Puppeteer Real Browser MCP Server

🚀 Puppeteer Real Browser MCP Server

このサーバーは、Model Context Protocol (MCP) を用いて、AIアシスタントに puppeteer-real-browser を介した強力で検知されにくいブラウザ自動化機能を提供します。

🚀 クイックスタート

初心者向けクイックスタート

これは何？

これは、Claude などのAIアシスタントが実際のウェブブラウザを制御できるようにする MCP (Model Context Protocol) サーバーです。Claude にウェブサイトとやり取りするための「手」を与えるようなもので、ボタンをクリックしたり、フォームに入力したり、スクリーンショットを撮ったりすることができ、ボット検知を回避します。

手順ごとのセットアップ

1. Node.js のインストール
   • nodejs.org にアクセスします。
   • Node.js (バージョン 18 以上) をダウンロードしてインストールします。
   • ターミナルまたはコマンドプロンプトを開き、node --version と入力してインストールを確認します。
2. Claude Desktop でのセットアップ (インストール不要) npx コマンドを使用すると、最新バージョンが自動的にダウンロードされて実行されるため、手動でのインストールは必要ありません。
3. Claude Desktop の設定
   • Windowsの場合
     1. ファイルエクスプローラーを開き、%APPDATA%\Claude\ に移動します。
     2. claude_desktop_config.json を開くか（存在しない場合は作成します）。
     3. 以下の設定を追加します。

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"]
    }
  }
}

- **Macの場合**
    1. ファインダーを開き、`Cmd+Shift+G` を押します。
    2. `~/Library/Application Support/Claude/` に移動します。
    3. `claude_desktop_config.json` を開くか（存在しない場合は作成します）。
    4. 上記と同じ設定を追加します。
- **Linuxの場合**
    1. `~/.config/Claude/` に移動します。
    2. `claude_desktop_config.json` を開くか（存在しない場合は作成します）。
    3. 上記と同じ設定を追加します。

4. Claude Desktop の再起動 Claude Desktop を完全に閉じてから再度開きます。
5. 動作確認 Claude Desktop で、「ブラウザを初期化して google.com に移動し、スクリーンショットを撮ってください」と入力します。 すべてが正常に動作していれば、Claude は以下のことができます。
   • ブラウザを起動する
   • Google に移動する
   • スクリーンショットを撮って表示する

このサーバーでできること

セットアップが完了すると、Claude に以下のことを依頼できます。

• ウェブサイトの閲覧：「amazon.com に移動して、ノートパソコンを検索してください」
• フォームの入力：「この問い合わせフォームに私の詳細を入力してください」
• スクリーンショットの撮影：「このページの様子を見せてください」
• データの抽出：「このECページのすべての商品価格を取得してください」
• タスクの自動化：「私のアカウントにログインして、請求書をダウンロードしてください」
• キャプチャの解決：「表示されるキャプチャを処理してください」

安全上の注意

• Claude が行っていることはブラウザウィンドウで確認できます。
• 機密性の高いアクションを承認する前に、Claude の行動を必ず確認してください。
• ブラウザウィンドウを表示したくない場合は、ヘッドレスモード (headless: true) を使用してください。
• ウェブサイトの利用規約を尊重してください。

✨ 主な機能

• デフォルトでステルスモード：すべてのブラウザインスタンスは反検知機能を使用します。
• 拡張されたページメソッド：page.realClick と page.realCursor をサポートします。
• 高度な設定：puppeteer-real-browser のすべてのオプションを完全にサポートします。
• 人間らしいアクション：検知を回避するための自然なやり取りツールが用意されています。
• 包括的なツールセット：16以上のツールがあり、すべてのブラウザ自動化ニーズに対応します。
• プロキシサポート：強化されたプライバシーのための組み込みプロキシ設定があります。
• キャプチャの処理：reCAPTCHA、hCaptcha、Turnstile の解決をサポートします。
• ターゲット管理：setTarget 関数をサポートします。
• エラーハンドリング：堅牢なエラーハンドリングとレポート機能があります。

📦 インストール

npm からのインストール

npm install -g puppeteer-real-browser-mcp-server

ソースからのインストール

# リポジトリをクローンする
git clone https://github.com/withLinda/puppeteer-real-browser-mcp-server.git
cd puppeteer-real-browser-mcp-server

# 依存関係をインストールする
npm install

# プロジェクトをビルドする
npm run build

💻 使用例

Claude Desktop での使用

Claude Desktop の設定に以下を追加します。

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"]
    }
  }
}

その他のAIアシスタントでの使用

サーバーを起動します。

puppeteer-real-browser-mcp-server

または、ソースからインストールした場合は、以下のコマンドを使用します。

npm start

サーバーは MCP プロトコルを使用して stdin/stdout を介して通信します。

基本的な使用法

基本的なウェブ閲覧

ユーザー: "ブラウザを初期化して example.com に移動してください"
AI: ステルスブラウザを初期化してウェブサイトに移動します。
[browser_init と navigate ツールを使用]

ユーザー: "メインコンテンツのスクリーンショットを撮ってください"
AI: ページのスクリーンショットを撮ります。
[screenshot ツールを使用]

フォームの自動化

ユーザー: "検索フォームに 'test query' を入力してください"
AI: 人間らしいタイピングで検索フィールドに入力します。
[human_like_type ツールをセレクターとテキストで使用]

ユーザー: "検索ボタンをクリックしてください"
AI: 人間らしい動きで検索ボタンをクリックします。
[human_like_click ツールを使用]

データの抽出

ユーザー: "このECページのすべての商品名を取得してください"
AI: ページから商品情報を抽出します。
[get_content ツールを適切なセレクターで使用]

ユーザー: "ページの内容をテキストとして保存してください"
AI: ページ全体のテキスト内容を取得します。
[get_content ツールを type: 'text' で使用]

高度なやり取り

ユーザー: "ドロップダウンメニューを real click で操作してください"
AI: 拡張された real_click メソッドを使用して、より良いインタラクションを行います。
[real_click ツールをセレクターとオプションで使用]

ユーザー: "カーソルを座標 500, 300 にスムーズに移動してください"
AI: 拡張された動きでカーソルを移動します。
[real_cursor ツールを x, y 座標とステップオプションで使用]

プロキシの使用

ユーザー: "プロキシサーバーを使用してブラウザを初期化してください"
AI: あなたのプロキシ設定でブラウザをセットアップします。
[browser_init を proxy: "https://proxy.example.com:8080" で使用]

📚 ドキュメント

利用可能なツール

コアブラウザツール

インタラクションツール

拡張された Puppeteer-Real-Browser ツール

人間らしい動作ツール

反検知ツール

高度な機能

人間らしいやり取り

サーバーには、人間の行動を模倣するためのいくつかのツールが含まれています。

• 人間らしいマウス動き：カーソルを自然な非線形の経路で移動させます。
• 可変のタイピング速度：キーストローク間にランダムな遅延を入れてタイピングします。
• ランダムなスクロール：自然なタイミングと可変の距離でスクロールします。 これらの機能は、ユーザーの行動パターンを分析する高度なボット検知システムによる検知を回避するのに役立ちます。

キャプチャの処理

サーバーは、一般的なキャプチャタイプの解決を基本的にサポートしています。

• reCAPTCHA
• hCaptcha
• Cloudflare Turnstile ただし、キャプチャの解決機能は、基盤となる puppeteer-real-browser の実装に依存します。

設定

カスタムオプションの設定（ヘッドレスモードなど）

ヘッドレスモードなどのカスタムオプションは、MCP 設定ファイルでは設定されません。代わりに、browser_init ツールを使用してブラウザを初期化する際に渡されます。 Claude にブラウザを初期化するように依頼するときは、以下のようなオプションを指定できます。

ヘッドレスモードを有効にし、30 秒のタイムアウトでブラウザを初期化してください

Claude は、適切なパラメータで browser_init ツールを使用します。

{
  "headless": true,
  "connectOption": {
    "timeout": 30000
  }
}

利用可能なブラウザオプション

browser_init で初期化するときは、以下の設定が可能です。

• headless: true/false（ヘッドレス動作に設定するには true）
• disableXvfb: true/false（X Virtual Framebuffer を無効にする）
• ignoreAllFlags: true/false（すべての Chrome フラグを無視する）
• proxy: "https://proxy:8080"（プロキシサーバーの URL）
• plugins: ["plugin1", "plugin2"]（読み込むプラグインの配列）
• connectOption: 追加の接続オプション、例えば:
  • slowMo: 250（操作をミリ秒単位で遅らせる）
  • timeout: 60,000（接続タイムアウト） MCP 設定ファイルは、Claude にサーバーの場所を伝えるだけで、すべてのブラウザ固有のオプションは、Claude との会話を通じて設定されます。

ブラウザオプションの例

browser_init でブラウザを初期化するときは、以下のように設定できます。

{
  "headless": false,
  "disableXvfb": false,
  "ignoreAllFlags": false,
  "proxy": "https://proxy:8080",
  "plugins": ["plugin1", "plugin2"],
  "connectOption": {
    "slowMo": 250,
    "timeout": 60000
  }
}

高度な設定例

プロキシの使用

{
  "headless": true,
  "proxy": "https://username:password@proxy.example.com:8080"
}

カスタムオプションでのステルスモード

{
  "headless": false,
  "ignoreAllFlags": true,
  "disableXvfb": false,
  "connectOption": {
    "slowMo": 100,
    "devtools": false
  }
}

拡張されたリアルブラウザ機能

real_click をオプションで使用する例：

{
  "selector": "#submit-button",
  "options": {
    "button": "left",
    "clickCount": 2,
    "delay": 150
  }
}

real_cursor を座標で使用する例：

{
  "x": 500,
  "y": 300,
  "options": {
    "steps": 30
  }
}

サーバーの設定

上級ユーザーは、ソースコードを編集することでサーバーの動作を変更できます。

• initializeBrowser 関数でデフォルトのビューポートサイズを変更する
• さまざまな操作のタイムアウト値を調整する
• デバッグログを有効にする

🔧 技術詳細

トラブルシューティング

一般的な問題

1. npx を使用すると "command not found" または "syntax error" が表示される
   • この問題はバージョン 1.0.3 で、適切なシェバンラインを追加することで修正されました。
   • 最新バージョンを使用していることを確認してください：npx puppeteer-real-browser-mcp-server@latest
   • グローバルインストールの場合は：npm install -g puppeteer-real-browser-mcp-server@latest
   • まだ問題が解決しない場合は、グローバルにインストールしてください：npm install -g puppeteer-real-browser-mcp-server
   • PATH に npm のグローバルバイナリが含まれていることを確認してください：npm config get prefix
2. ブラウザが起動しない
   • Chrome/Chromium がインストールされていることを確認してください。
   • Linux の場合：依存関係をインストールしてください：sudo apt-get install -y chromium-browser
   • Windows の場合：Chrome がインストールされていることを確認してください。
   • まず headless: true で試してみてください。
3. Claude が MCP サーバーを認識しない
   • claude_desktop_config.json が正しい場所にあることを確認してください。
   • JSON 構文が有効であることを確認してください（jsonlint.com を使用）。
   • Claude Desktop を完全に再起動してください。
   • Claude Desktop のエラーメッセージを確認してください。
4. Permission denied エラーが発生する
   • Linux/Mac の場合：sudo npm install -g puppeteer-real-browser-mcp-server を試してください。
   • または、sudo を使用せずに Node.js を管理するために nvm を使用してください。
   • Windows の場合：コマンドプロンプトを管理者として実行してください。
5. 検知問題が発生する
   • 基本的なクリックの代わりに real_click と real_cursor を使用してください。
   • 人間らしいツールを有効にしてください：human_like_click, human_like_type
   • random_scroll でランダムな遅延を追加してください。
   • 必要に応じてプロキシを使用してください：proxy: "http://proxy.example.com:8080"
6. メモリリークが発生する
   • 作業が終了したら、必ず browser_close でブラウザインスタンスを閉じてください。
   • 前のブラウザを閉じずに複数のブラウザを初期化しないでください。
   • クリーンアップを妨げる可能性のあるキャッチされていない例外を確認してください。
7. タイムアウトエラーが発生する
   • タイムアウト値を増やしてください：{ "timeout": 60000 }
   • 要素とのやり取りの前に wait ツールを使用してください。
   • ネットワーク接続とウェブサイトの応答時間を確認してください。

よくある質問

Q: これはヘッドレスブラウザで動作しますか？ A: はい、browser_init オプションで headless: true を設定します。

Q: 一度に複数のブラウザを使用できますか？ A: 現在は1つのブラウザインスタンスをサポートしています。新しいブラウザを起動する前に、現在のブラウザを閉じてください。

Q: どのようなキャプチャを解決できますか？ A: puppeteer-real-browser を通じて、reCAPTCHA、hCaptcha、Cloudflare Turnstile をサポートしています。

Q: これはウェブサイトによって検知されますか？ A: puppeteer-real-browser には反検知機能が含まれていますが、どの解決策も100%検知されないわけではありません。

Q: カスタムの Chrome 拡張機能を使用できますか？ A: はい、browser_init の plugins オプションを通じて使用できます。

Q: すべてのオペレーティングシステムで動作しますか？ A: はい、Windows、macOS、Linux でテストされています。

デバッグモード

デバッグログを有効にするには、以下のコマンドを使用します。

DEBUG=true npm start

または、ソースから実行する場合は、以下のコマンドを使用します。

DEBUG=true npm run dev

ヘルプの取得

まだ問題が解決しない場合は、以下の手順を行ってください。

1. GitHub Issues を確認してください。
2. 新しいイシューを作成してください。
   • あなたのオペレーティングシステム
   • Node.js のバージョン (node --version)
   • npm のバージョン (npm --version)
   • 完全なエラーメッセージ
   • 問題を再現する手順

開発

プロジェクト構造

puppeteer-real-browser-mcp-server/
├── src/
│   ├── index.ts         # メインサーバーの実装
│   └── stealth-actions.ts # 人間らしいインタラクション関数
├── test/
│   └── test-server.ts   # テストスクリプト
├── package.json
└── tsconfig.json

ソースからのビルド

# 依存関係をインストールする
npm install

# 開発モードで実行する
npm run dev

# 本番用にビルドする
npm run build

# サーバーをテストする
npm test

新しいツールの追加

新しいツールを追加するには、以下の手順を行います。

1. src/index.ts の TOOLS 配列にツール定義を追加します。
2. CallToolRequestSchema ハンドラーでツールハンドラーを実装します。
3. 新しいツールの機能をテストします。

🤝 コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。

1. リポジトリをフォークします。
2. あなたの機能ブランチを作成します (git checkout -b feature/amazing-feature)。
3. 変更をコミットします (git commit -m 'Add some amazing feature')。
4. ブランチにプッシュします (git push origin feature/amazing-feature)。
5. プルリクエストを開きます。

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています - 詳細については LICENSE ファイルを参照してください。