Puppeteer MCP サーバー

この MCP サーバーは、Puppeteer を通じてブラウザ自動化機能を提供し、新しいブラウザ インスタンスと既存の Chrome ウィンドウの両方との対話を可能にします。

了承

このプロジェクトは、@modelcontextprotocol/server-puppeteerに触発された実験的な実装です。同様の目標とコンセプトを共有しながらも、モデルコンテキストプロトコルを介したブラウザ自動化への代替アプローチを模索しています。

Related MCP server: Steel Puppeteer

特徴

• ウェブページをナビゲートする

• スクリーンショットを撮る

• 要素をクリック

• フォームに記入する

• オプションを選択

• ホバー要素

• JavaScriptを実行する

• スマートな Chrome タブ管理:

  • アクティブなChromeタブに接続する

  • 既存の Chrome インスタンスを保持する

  • インテリジェントな接続処理

プロジェクト構造

/
├── src/
│   ├── config/        # Configuration modules
│   ├── tools/         # Tool definitions and handlers
│   ├── browser/       # Browser connection management
│   ├── types/         # TypeScript type definitions
│   ├── resources/     # Resource handlers
│   └── server.ts      # Server initialization
├── index.ts          # Entry point
└── README.md        # Documentation

インストール

オプション1: npmからインストールする

npm install -g puppeteer-mcp-server

npx を使用すると、インストールせずに直接実行することもできます。

npx puppeteer-mcp-server

オプション2: ソースからインストールする

1. このリポジトリをクローンするか、ソースコードをダウンロードしてください

2. 依存関係をインストールします:

npm install

3. プロジェクトをビルドします。

npm run build

4. サーバーを実行します。

npm start

MCP サーバーの構成

このツールを Claude で使用するには、MCP 設定構成ファイルに追加する必要があります。

Claudeデスクトップアプリ用

Claude Desktop 構成ファイル (Windows の場合は%APPDATA%\Claude\claude_desktop_config.json 、macOS の場合は~/Library/Application Support/Claude/claude_desktop_config.json ) に次のコードを追加します。

npm 経由でグローバルにインストールした場合:

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

npx を使用する (インストールなし):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

ソースからインストールした場合:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

Claude VSCode拡張機能

Claude VSCode 拡張機能 MCP 設定ファイル (Windows の場合は%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json macOS の場合は~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ) に次の内容を追加します。

npm 経由でグローバルにインストールした場合:

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

npx を使用する (インストールなし):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

ソースからインストールした場合:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

ソースインストールの場合は、 path/to/puppeteer-mcp-serverこのツールをインストールした実際のパスに置き換えます。

使用法

標準モード

デフォルトでは、サーバーは新しいブラウザ インスタンスを起動します。

アクティブタブモード

既存の Chrome ウィンドウに接続するには:

1. 既存のChromeインスタンスを完全に閉じます

2. リモート デバッグを有効にして Chrome を起動します。

   # Windows
   "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
   
   # macOS
   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
   
   # Linux
   google-chrome --remote-debugging-port=9222

3. Chromeで目的のウェブページに移動します

4. puppeteer_connect_active_tabツールを使用して接続します。

   {
     "targetUrl": "https://example.com", // Optional: specific tab URL
     "debugPort": 9222 // Optional: defaults to 9222
   }

サーバーは次のことを行います。

• リモートデバッグが有効になっているChromeインスタンスを検出して接続します

• Chrome インスタンスを保存します（閉じません）

• 拡張機能以外のタブを見つけて接続する

• 接続に失敗した場合は明確なエラーメッセージを表示する

利用可能なツール

操り人形師_connect_active_tab

リモート デバッグが有効になっている既存の Chrome インスタンスに接続します。

• オプション:

  • targetUrl - 接続する特定のタブのURL

  • debugPort - Chrome デバッグ ポート (デフォルト: 9222)

操り人形師ナビゲート

URL に移動します。

• 必須: url - 移動先のURL

操り人形師のスクリーンショット

現在のページまたは特定の要素のスクリーンショットを撮ります。

• 必須: name - スクリーンショットの名前

• オプション:

  • selector - スクリーンショットを撮る要素の CSS セレクター

  • width - ピクセル単位の幅（デフォルト: 800）

  • height - ピクセル単位の高さ（デフォルト: 600）

操り人形師クリック

ページ上の要素をクリックします。

• 必須: selector - クリックする要素の CSS セレクター

操り人形師の塗りつぶし

入力フィールドに入力します。

• 必須：

  • selector - 入力フィールドの CSS セレクター

  • value - 入力するテキスト

操り人形師の選択

ドロップダウンメニューを使用します。

• 必須：

  • selector - 選択要素の CSS セレクター

  • value - 選択するオプション値

操り人形師_hover

要素の上にマウスを置きます。

• 必須: selector - 要素をホバーするための CSS セレクター

操り人形師の評価

ブラウザコンソールで JavaScript を実行します。

• 必須: script - 実行するJavaScriptコード

セキュリティに関する考慮事項

リモート デバッグを使用する場合:

• 信頼できるネットワークでのみ有効にする

• 固有のデバッグポートを使用する

• 使用していないときはデバッグポートを閉じる

• デバッグポートをパブリックネットワークに公開しないでください

ログ記録とデバッグ

ファイルベースのログ記録

サーバーは Winston を使用して包括的なログ記録を実装します。

• 場所: logs/ディレクトリ

• ファイルパターン: mcp-puppeteer-YYYY-MM-DD.log

• ログローテーション:

  • 毎日のローテーション

  • 最大サイズ: ファイルあたり20MB

  • 保存期間: 14日間

  • 古いログの自動圧縮

ログレベル

• DEBUG: 詳細なデバッグ情報

• 情報: 一般的な運用情報

• 警告: 警告メッセージ

• エラー: エラーイベントと例外

記録された情報

• サーバーの起動/シャットダウンイベント

• ブラウザ操作（起動、接続、閉じる）

• ナビゲーションの試みと結果

• ツールの実行と結果

• スタックトレースを含むエラーの詳細

• ブラウザコンソール出力

• リソース使用量（スクリーンショット、コンソールログ）

エラー処理

サーバーは、次の詳細なエラー メッセージを提供します。

• 接続失敗

• 欠けている要素

• 無効なセレクタ

• JavaScript実行エラー

• スクリーンショットの失敗

各ツール呼び出しは次を返します:

• 成功/失敗ステータス

• 失敗した場合の詳細なエラーメッセージ

• 成功した場合の操作結果データ

すべてのエラーは、次のログ ファイルにも記録されます。

• タイムスタンプ

• エラーメッセージ

• スタック トレース (利用可能な場合)

• コンテキスト情報

貢献

貢献を歓迎します！プルリクエストの送信方法、問題の報告方法、プロジェクトへの貢献方法の詳細については、貢献ガイドラインをお読みください。

ライセンス

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