Puppeteer MCP Server (Python Implementation)

Puppeteer MCP Server（Python 実装）

Playwright（Python における Puppeteer 相当）を使用してブラウザー自動化機能を提供する Model Context Protocol サーバーです。このサーバーにより、LLM は実際のブラウザー環境でウェブページを操作し、スクリーンショットを撮影し、JavaScript を実行できます。

概要

この Python 実装は、TypeScript 版と同じ機能を提供しつつ、エラー処理とログ記録を改善した安定した代替手段です。Puppeteer の Python 相当である Playwright を使用し、堅牢なブラウザー自動化機能を提供します。

主な機能

• ブラウザーの完全な自動化
• ページのナビゲーション
• スクリーンショットの撮影（ページ全体または要素）
• フォーム操作（クリックと入力）
• JavaScript の実行
• コンソールログの監視
• タイムアウトの設定
• 詳細なエラー処理
• 包括的なログ記録

前提条件

• Python 3.8+
• pip（Python パッケージインストーラー）

インストール

1. 必要なパッケージをインストールします：

pip install -r requirements.txt

2. Playwright のブラウザーをインストールします：

playwright install

使用方法

サーバーの起動

サーバーを直接実行します：

python puppeteer_server.py

Claude Desktop の設定

Claude の設定ファイルに以下を追加します：

{
  "mcpServers": {
    "puppeteer": {
      "command": "python",
      "args": ["path/to/puppeteer.py"]
    }
  }
}

利用可能なツール

puppeteer_navigate

ブラウザーで任意の URL に移動します。

{
  "name": "puppeteer_navigate",
  "arguments": {
    "url": "https://example.com",
    "timeout": 60000  // optional, defaults to 60000ms
  }
}

puppeteer_screenshot

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

{
  "name": "puppeteer_screenshot",
  "arguments": {
    "name": "my_screenshot",
    "selector": "#specific-element",  // optional
    "width": 1280,  // optional, default: 1280
    "height": 720,  // optional, default: 720
    "timeout": 30000  // optional, defaults to 30000ms
  }
}

puppeteer_click

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

{
  "name": "puppeteer_click",
  "arguments": {
    "selector": ".button-class",
    "timeout": 30000  // optional, defaults to 30000ms
  }
}

puppeteer_fill

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

{
  "name": "puppeteer_fill",
  "arguments": {
    "selector": "#input-id",
    "value": "text to fill",
    "timeout": 30000  // optional, defaults to 30000ms
  }
}

puppeteer_evaluate

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

{
  "name": "puppeteer_evaluate",
  "arguments": {
    "script": "document.title",
    "timeout": 30000  // optional, defaults to 30000ms
  }
}

エラー処理

このサーバーは、よくある状況について詳細なエラーメッセージを提供します：

• ナビゲーションの失敗
• 要素が見つからない
• タイムアウトエラー
• JavaScript の実行エラー
• スクリーンショットの撮影失敗

ログ記録

異なるレベルを使用した包括的なログ記録を実装しています：

• INFO：標準的な操作
• ERROR：操作の失敗
• DEBUG：実行に関する詳細情報

注意事項

• デバッグしやすいよう、ブラウザーはヘッドレスモードを無効にして起動します
• デフォルトのビューポートサイズは 1280x720 です
• すべてのタイムアウトは設定可能です
• コンソールログは取得され、保存されます
• スクリーンショットは base64 エンコードでメモリに保存されます

貢献

貢献を歓迎します！プルリクエストを送信する前に、リポジトリの貢献ガイドラインをお読みください。

作者

Todd Wolven - AI ソフトウェア開発リード、オープンソース GenAI エンジニア

ライセンス

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