Puppeteer Real Browser MCP Server

Puppeteer Real Browser MCP サーバー

MCP 互換の AI アシスタントに、開いて、移動して、読み取り、操作できるローカルの Chrome ブラウザーを与えます。

メンテナンス中: このプロジェクトはまだ変更が続いています。main ブランチは、npm で公開されているパッケージより新しい可能性があります。上の npm バッジは、@latest で使用される公開バージョンを示しています。

できること

このパッケージは、ローカルの Model Context Protocol (MCP) サーバーとして動作します。MCP クライアントがサーバーを起動し、サーバーがブラウザー自動化用に 1 つの Chrome プロセスを起動します。

主な機能:

• デフォルトでは表示されるブラウザーを開き、オプションでヘッドレスモードも利用可能
• ページを移動し、HTML またはテキストを読み取る
• 要素を検索し、クリックし、入力し、待機し、スクロールする
• rebrowser-puppeteer-core といくつかの検出回避設定を使用する
• Windows、macOS、Linux で Chrome を検出する
• カスタムの Chrome パス、プロキシ、専用の自動化プロファイルをサポートする
• 起動した正確な Chrome プロセスを追跡し、そのプロセスのみを終了する
• ページ操作の前にコンテンツ優先のワークフローを強制する

ブラウザー自動化が見えないものになることはありません。ウェブサイトは依然としてそれを検出したり、ブロックしたりする可能性があります。

安全性と現在の制限

サーバーを使用する前に、以下をお読みください:

• 自動化が許可されているウェブサイトでのみ使用してください。
• ログイン、フォーム、購入、ダウンロード、その他の機密性の高い操作を承認する前に、ツール呼び出しを確認してください。
• ブラウザーとファイルのツールは、通常のユーザー権限で実行されます。
• サーバーは一度に 1 つのブラウザーセッションをサポートします。
• solve_captcha は現在プレースホルダーです。CAPTCHA 解決サービスは使用しません。ブラウザーの起動時に、検出された Turnstile ウィジェットに対してベストエフォートのクリックを行うだけです。
• save_content_as_markdown はサーバーに一覧表示されていますが、現在のワークフローバリデーターがそれをブロックします。これは既知のコードの問題です。

要件

• Node.js 18 以降
• npm と npx（通常の Node.js インストーラーに含まれています）
• Google Chrome または Chromium
• ローカルの stdio サーバーを起動できる MCP クライアント

Claude Desktop は macOS と Windows で利用できます。他の MCP クライアントは Linux でこのサーバーを使用できます。

クイックスタート

このパッケージをグローバルにインストールする必要はありません。MCP クライアントが必要としたときに、npx が公開されているパッケージをダウンロードして実行できます。

-y オプションは、npm のインストールに関する質問が MCP サーバーの起動を妨げるのを防ぎます。

Claude Desktop

1. Claude Desktop → Settings → Developer → Edit Config を開きます。
2. mcpServers 内に次のサーバーを追加します:

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

1. ファイルを保存します。
2. Claude Desktop を完全に終了し、再度開きます。

Claude Desktop はこのファイルを次の場所に保存します:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

現在の Claude Desktop の手順については、公式のローカル MCP サーバーガイドを参照してください。

Claude Code

次を実行します:

claude mcp add --transport stdio puppeteer-real-browser \
  -- npx -y puppeteer-real-browser-mcp-server@latest

次に接続を確認します:

claude mcp get puppeteer-real-browser

Claude Code 内では、/mcp でもサーバーステータスが表示されます。

デフォルトのスコープは現在のプロジェクトに対してローカルです。すべてのプロジェクトでサーバーを使用したい場合は、サーバー名の前に --scope user を追加します。スコープの詳細については、公式の Claude Code MCP ガイドを参照してください。

Cursor

1 つのプロジェクトでは .cursor/mcp.json を作成し、すべてのプロジェクトでは ~/.cursor/mcp.json を作成します:

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

ファイルを保存した後に Cursor を再起動します。現在の構成場所と形式については、公式の Cursor MCP ガイドを参照してください。

その他の MCP クライアント

このコマンドと引数リストを使用して、ローカルの stdio サーバーを使用します:

command: npx
args: -y puppeteer-real-browser-mcp-server@latest

サーバーは標準入力と標準出力を介して通信します。MCP クライアントは、ツールを使用している間、プロセスを開いたままにしておく必要があります。

セットアップのテスト

AI アシスタントに次のように尋ねてください:

ブラウザを起動し、https://example.com を開き、ページのテキストを読み取り、 その後ブラウザを閉じてください。

想定されるツールの実行順序は次のとおりです:

browser_init → navigate → get_content → browser_close

利用可能なツール

サーバーは 11 個のツールを公開しています。

ツール	目的	必須入力
browser_init	管理対象の Chrome セッションを開始または再利用します	なし
navigate	URL を開きます	url
get_content	ページ全体または選択した HTML/テキストを読み取ります	なし
find_selector	要素のテキストから CSS セレクターを検索します	text
click	要素をクリックします	selector
type	入力をクリアしてテキストを入力します	selector、text
wait	セレクター、ナビゲーション、または時間を待機します	type、value
random_scroll	さまざまなタイミングと距離でスクロールします	なし
solve_captcha	プレースホルダーの試行結果を返します	type
save_content_as_markdown	.md として保存します。現在はブロックされています	filePath
browser_close	管理対象のブラウザを閉じ、ワークフロー状態をリセットします	なし

コンテンツ優先のワークフロー

サーバーは盲目的な操作をブロックします。次の順序を使用してください:

browser_init → navigate → get_content → find_selector → click or type

新しいナビゲーションの後は、クリックまたは入力を行う前に、再度 get_content を呼び出してください。 ページのコンテンツの読み込みが遅い場合は、ナビゲーションの後に wait を呼び出すことができます。

ブラウザの設定

ブラウザのオプションは browser_init への入力です。これらはトップレベルの MCP サーバー設定ではありません。

オプション	意味
headless	ブラウザウィンドウを非表示にするには true を設定します。デフォルト: false。
proxy	http://proxy.example.com:8080 のようなプロキシ URL。
profilePath	専用の自動化プロファイルのパス。
disableXvfb	Linux で Xvfb を起動するには false を設定します。
connectOption.timeout	接続およびセットアップのタイムアウト (ミリ秒単位)。
connectOption.slowMo	操作の遅延 (ミリ秒単位)。
customConfig.chromePath	Chrome 実行ファイルへの絶対パス。
customConfig.chromeFlags	カスタムフラグ。サーバーのフラグリストを置き換えます。
contentPriority	コンテンツ優先の提案設定。

contentPriority は prioritizeContent と autoSuggestGetContent という Boolean 値を持つオブジェクトです。これは提案を変更しますが、 必須のコンテンツ優先ワークフローを削除するものではありません。

リクエスト例:

{
  "headless": true,
  "proxy": "http://proxy.example.com:8080",
  "connectOption": {
    "timeout": 60000,
    "slowMo": 100
  },
  "customConfig": {
    "chromePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  }
}

Chrome のパス

サーバーはまず次の環境変数を確認します:

1. CHROME_PATH
2. PUPPETEER_EXECUTABLE_PATH

どちらもファイルを指していない場合、サーバーは一般的な Chrome および Chromium の場所を確認します。Windows では、レジストリと一般的なポータブルパスも確認します。

MCP クライアントの設定で CHROME_PATH を設定できます:

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": [
        "-y",
        "puppeteer-real-browser-mcp-server@latest"
      ],
      "env": {
        "CHROME_PATH": "/absolute/path/to/chrome"
      }
    }
  }
}

PROXY_URL はサポートされている環境変数ではありません。代わりに browser_init にプロキシを渡してください。

ブラウザの所有権保護

サーバーは、起動した Chrome プロセスの正確なランチャーハンドルとプロセス ID を保持します。 通常の終了、起動の失敗、タイムアウト、MCP の切断、および シグナルによるシャットダウンは、すべてそのハンドルを通じてクリーンアップされます。プロセス名で Chrome を検索したり 閉じたりすることはありません。

安全のため、サーバーは別のブラウザに接続したり、 個人の Chrome プロファイルの所有権を取得したりする可能性のある設定を拒否します:

• customConfig.userDataDir
• customConfig.port
• customConfig.portStrictMode
• customConfig.handleSIGINT
• connectOption.browserURL
• connectOption.browserWSEndpoint
• connectOption.transport
• カスタム Chrome フラグ内の --remote-debugging-port、--remote-debugging-pipe、および --user-data-dir

永続的な自動化データには profilePath を使用してください。ディレクトリは 絶対パスであり、空であるか、すでにこのサーバーによって所有されているとマークされている必要があります。

トラブルシューティング

MCP サーバーが表示されない

1. ツールがインストールされていることを確認します:

   node --version
   npm --version
   npx --version
   

2. Node.js がバージョン 18 以降であることを確認します。

3. JSON ファイルにカンマや引用符の欠落がないか確認します。

4. MCP クライアントを完全に終了してから再度開きます。

5. デスクトップアプリが npx を見つけられない場合は、その絶対パスを command として使用します。 macOS/Linux では which npx、Windows では where npx を実行して見つけます。

Claude Desktop のログはここに保存されます:

• macOS: ~/Library/Logs/Claude
• Windows: %APPDATA%\Claude\logs

Chrome が見つからない

実際の Chrome 実行ファイルを見つけて、MCP クライアントの設定で CHROME_PATH を設定します。一般的な例は次のとおりです:

• Windows: C:/Program Files/Google/Chrome/Application/chrome.exe
• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Linux: /usr/bin/google-chrome または /usr/bin/chromium

Chrome のパスの問題を解決するためだけに、MCP クライアントを管理者として実行したり、sudo npm install -g を使用したりしないでください。

ターミナルで実行するとサーバーが固まったように見える

これは正常な場合があります。stdio MCP サーバーは、MCP クライアントからのプロトコルメッセージを待機します。プロセスに入力する代わりに、MCP Inspector を使用してください。

公開されているパッケージをテストします:

npx -y @modelcontextprotocol/inspector \
  npx puppeteer-real-browser-mcp-server@latest

使用方法の詳細については、公式の MCP Inspector ガイドを参照してください。

ページのアクションがブロックされる

必要なワークフローに従ってください:

1. browser_init
2. navigate
3. get_content
4. セレクターが必要な場合は find_selector
5. click または type

ページが変更された場合は、再度 get_content を呼び出します。

ブラウザ接続がタイムアウトする

• Chrome のパスが存在することを確認します。
• browser_close で現在の管理対象ブラウザを閉じてから、再度起動します。
• browser_init の入力で connectOption.timeout を増やします。
• セキュリティソフトが子 Chrome プロセスをブロックしていないか確認します。
• 問題を報告する際は、完全なエラーメッセージを含めてください。

ヘルプを得る

GitHub issueを検索するか、開いてください。以下を含めてください:

• オペレーティングシステム
• Node.js と npm のバージョン
• MCP クライアントの名前とバージョン
• Chrome のバージョンと実行ファイルのパス
• 完全なエラーメッセージ
• 問題を再現する正確な手順

パスワード、Cookie、トークン、非公開のページ内容を含めないでください。

開発

ソースから実行する

git clone https://github.com/withLinda/puppeteer-real-browser-mcp-server.git
cd puppeteer-real-browser-mcp-server
npm ci
npm run build

MCP Inspector でローカルビルドをテストします:

npx -y @modelcontextprotocol/inspector node dist/index.js

ローカルビルドを MCP クライアントで使用するには、絶対パスを使用します:

{
  "mcpServers": {
    "puppeteer-real-browser-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/puppeteer-real-browser-mcp-server/dist/index.js"
      ]
    }
  }
}

プロジェクト構成

src/index.ts                     MCP stdio server and request handlers
src/tool-definitions.ts          Tool names and input schemas
src/browser-manager.ts           Browser state, detection, and configuration
src/managed-browser-session.ts   Owned Chrome launch and cleanup
src/handlers/                    Tool implementations
src/*.test.ts                    Unit and regression tests
test/integration/                MCP protocol integration tests
test/e2e/                        Real-browser tests
test/safety/                     Browser cleanup safety guard
scripts/check-packaged-server.ts Package smoke test

テストワークフロー

動作の変更には TDD を使用します: 失敗するテストを 1 つ書き、それを成功させてから、コードを整理します。

# Browser cleanup safety guard
npm run test:safety

# Fast source tests
npm run test:unit

# MCP protocol integration tests
npm run test:integration

# Build the package
npm run build

# Test the built npm package shape and stdio lifecycle
npm run test:package:smoke:built

# Real Chrome tests
npm run test:e2e

# Release-focused automated checks
npm run test:all

TDD 中は、npm run test:watch を使用します。実際のブラウザのテストを実行する前に、マシン上で既に開いている Chrome プロセスに注意してください。テスト後、テストによって起動された Chrome プロセスのみが閉じられたことを確認します。

コントリビューション

Issue とプルリクエストを歓迎します。コード変更の場合:

1. 焦点を絞ったブランチを作成します。
2. 1 つの動作に対する失敗するテストを追加します。
3. テストを成功させる最小限のコード変更を行います。
4. テストがグリーンのままリファクタリングします。
5. 安全性、ソース、ビルド、パッケージのチェックを実行します。
6. コミットメッセージで、根本原因、解決策、防止策、検証について説明します。

ライセンス

このプロジェクトは MIT License を使用しています。

謝辞

元の実装と公開 API は、ZFC Digital による puppeteer-real-browser に基づいていました。現在のソースは、そのサポート終了となったランタイム依存関係を、chrome-launcher、rebrowser-puppeteer-core、ghost-cursor から構築された内部の管理対象ランチャーに置き換えています。