Puppeteer MCP Server

Puppeteer MCP サーバー

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

謝辞

このプロジェクトは、@modelcontextprotocol/server-puppeteer に着想を得た実験的な実装です。同様の目標や概念を共有しつつ、Model Context Protocol を通じたブラウザー自動化の別のアプローチを探っています。

機能

• ウェブページに移動する
• スクリーンショットを撮影する
• 要素をクリックする
• フォームに入力する
• オプションを選択する
• 要素にカーソルを合わせる
• 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 Desktop アプリの場合

以下を 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 インスタンスを維持する（終了しません）
• 拡張機能以外のタブを見つけて接続する
• 接続に失敗した場合、わかりやすいエラーメッセージを表示する

使用可能なツール

puppeteer_connect_active_tab

リモートデバッグを有効にした既存の Chrome インスタンスに接続します。

• 任意：
  • targetUrl - 接続する特定のタブの URL
  • debugPort - Chrome のデバッグポート（デフォルト：9222）

puppeteer_navigate

URL に移動します。

• 必須：url - 移動先の URL

puppeteer_screenshot

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

• 必須：name - スクリーンショットの名前
• 任意：
  • selector - スクリーンショットを撮影する要素の CSS セレクター
  • width - ピクセル単位の幅（デフォルト：800）
  • height - ピクセル単位の高さ（デフォルト：600）

puppeteer_click

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

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

puppeteer_fill

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

• 必須：
  • selector - 入力フィールドの CSS セレクター
  • value - 入力するテキスト

puppeteer_select

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

• 必須：
  • selector - select 要素の CSS セレクター
  • value - 選択するオプションの値

puppeteer_hover

要素にカーソルを合わせます。

• 必須：selector - カーソルを合わせる要素の CSS セレクター

puppeteer_evaluate

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

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

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

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

• 信頼できるネットワークでのみ有効にしてください
• デバッグポートには一意の番号を使用してください
• 使用していないときはデバッグポートを閉じてください
• デバッグポートをパブリックネットワークに公開しないでください

ログとデバッグ

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

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

• 保存場所：logs/ ディレクトリ
• ファイルパターン：mcp-puppeteer-YYYY-MM-DD.log
• ログローテーション：
  • 毎日ローテーション
  • 最大サイズ：ファイルあたり 20MB
  • 保持期間：14 日間
  • 古いログを自動的に圧縮

ログレベル

• DEBUG：詳細なデバッグ情報
• INFO：一般的な運用情報
• WARN：警告メッセージ
• ERROR：エラーイベントと例外

ログに記録される情報

• サーバーの起動／終了イベント
• ブラウザー操作（起動、接続、終了）
• ナビゲーションの試行と結果
• ツールの実行と結果
• スタックトレースを含むエラーの詳細
• ブラウザーコンソールの出力
• リソース使用状況（スクリーンショット、コンソールログ）

エラー処理

サーバーは、以下のエラーについて詳細なメッセージを提供します。

• 接続失敗
• 要素が見つからない
• 無効なセレクター
• JavaScript の実行エラー
• スクリーンショットの失敗

各ツール呼び出しは、以下を返します。

• 成功／失敗のステータス
• 失敗した場合の詳細なエラーメッセージ
• 成功した場合の操作結果データ

すべてのエラーは、以下の情報とともにログファイルにも記録されます。

• タイムスタンプ
• エラーメッセージ
• スタックトレース（取得可能な場合）
• コンテキスト情報

コントリビューション

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

ライセンス

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