🚀 MCP Browser Agent
強力なModel Context Protocol (MCP) の統合機能で、Claude Desktopに自動化されたブラウザ操作機能を提供します。

強力なModel Context Protocol (MCP) の統合機能で、Claude Desktopに自動化されたブラウザ操作機能を提供します。 |
|
✨ 主な機能
-
高度なブラウザ自動化
- カスタマイズ可能なロード戦略で任意のURLに移動
- 全ページまたは要素特定のスクリーンショットを撮影
- 正確なDOM操作(クリック、入力、選択、ホバー)を実行
- コンソールログをキャプチャしながら、ブラウザコンテキストで任意のJavaScriptを実行
-
強力なAPIクライアント
- HTTPリクエスト(GET、POST、PUT、PATCH、DELETE)を実行
- リクエストヘッダーとボディコンテンツを設定
- JSON形式でレスポンスデータを処理
- 詳細なフィードバックを伴うエラーハンドリング
-
MCPリソース管理
- ブラウザコンソールログをリソースとしてアクセス
- MCPリソースインターフェイスを通じてスクリーンショットを取得
- ヘッドフルブラウザインスタンスで永続的なセッションを維持
-
AIエージェント機能
- 複雑なタスクのために複数のブラウザ操作を連鎖させる
- 多段階の指示に従い、インテリジェントなエラー回復を行う
- 自然言語指示による技術的タスクの自動化
🎥 デモ
タイムスタンプ:
動画の任意のタイムスタンプをクリックすると、その部分にジャンプします。
00:00 - MCPのGoogle検索
Googleのホームページに移動し、「Model Context Protocol」を検索します。Claude DesktopがMCP統合機能を使用して基本的なウェブ検索を実行し、結果を処理するデモです。
00:33 - スクリーンショットの撮影
カスタムファイル名で検索結果のスクリーンショットを撮影し、Finderで表示します。Claudeがブラウザ自動化中にウェブページからビジュアルコンテンツをキャプチャして保存する方法を示しています。
01:00 - Wikipedia検索
Wikipedia.orgに移動し、「Model Context Protocol」を検索します。ClaudeがMCP統合機能を通じて異なるウェブサイトとその検索機能とやり取りできる能力を示しています。
01:38 - ドロップダウンメニューの操作I
テストウェブサイト(the-internet.herokuapp.com/dropdown)に移動し、ドロップダウンメニューから「Option 1」を選択します。Claudeがフォーム要素とやり取りし、選択を行う能力を示しています。
01:56 - ドロップダウンメニューの操作II
同じドロップダウンメニューから選択を「Option 2」に変更します。Claudeが同じフォーム要素を複数回操作し、異なる選択を行う能力を示しています。
02:09 - ログインフォームの入力
ログインページ(the-internet.herokuapp.com/login)に移動し、ユーザー名フィールドに「tomsmith」、パスワードフィールドに「SuperSecretPassword!」を入力します。フォーム入力の自動化を示しています。
02:28 - ログイン送信
ログイン資格情報を送信し、認証プロセスを完了します。Claudeがフォーム送信をトリガーし、多段階プロセスをナビゲートする能力を示しています。
02:36 - APIリクエストの実行
JSONPlaceholder APIエンドポイントにGETリクエストを実行します。ClaudeがMCP統合機能を通じて直接API呼び出しを行い、返されたデータを処理する能力を示しています。
📋 必要条件
- Node.js 16以上
- Claude Desktop
- Playwright依存関係
ブラウザサポート
npm init playwright@latest
このパッケージには、ブラウザ自動化を実行するために必要なPlaywrightとその依存関係が含まれています。npm install
を実行すると、必要なPlaywright依存関係がインストールされます。このパッケージは以下のブラウザをサポートしています。
- Chrome(デフォルト)
- Firefox
- Microsoft Edge
- WebKit(Safariエンジン)
初めてブラウザタイプを使用するとき、Playwrightは必要に応じて対応するブラウザドライバを自動的にインストールします。以下のコマンドで手動でインストールすることもできます。
npx playwright install chrome
npx playwright install firefox
npx playwright install webkit
npx playwright install msedge
Safariに関する注意: PlaywrightはSafariブラウザを直接サポートしていません。代わりに、Safariを動作させるブラウザエンジンであるWebKitを使用します。
Edgeに関する注意: ブラウザタイプとしてEdgeを選択すると、エージェントは実際にはMicrosoft Edge(Chromiumではない)を起動します。技術的には、PlaywrightではEdgeはChromiumブラウザインスタンスを使用して「msedge」チャネルパラメータで起動されます。なぜなら、Microsoft EdgeはChromiumをベースにしているからです。
📦 インストール
手動インストール
- このリポジトリをクローンまたはダウンロードします。
git clone https://github.com/imprvhub/mcp-browser-agent
cd mcp-browser-agent
- 依存関係をインストールします。
npm install
- プロジェクトをビルドします。
npm run build
🚀 MCPサーバーの起動
MCPサーバーを起動する方法は2つあります。
オプション1: 手動で起動
- ターミナルまたはコマンドプロンプトを開きます。
- プロジェクトディレクトリに移動します。
- サーバーを直接起動します。
node dist/index.js
Claude Desktopを使用している間、このターミナルウィンドウを開いたままにしておきます。サーバーはターミナルを閉じるまで実行されます。
オプション2: Claude Desktopと自動起動(定期的な使用に推奨)
Claude Desktopは必要に応じてMCPサーバーを自動的に起動することができます。これを設定するには、以下の手順を行います。
設定
Claude Desktopの設定ファイルは以下の場所にあります。
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
このファイルを編集して、Browser Agent MCPの設定を追加します。ファイルが存在しない場合は、作成します。
{
"mcpServers": {
"browserAgent": {
"command": "node",
"args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
"--browser",
"chrome"
]
}
}
}
重要: ABSOLUTE_PATH_TO_DIRECTORY
を、MCPをインストールした完全な絶対パスに置き換えてください。
- macOS/Linuxの例:
/Users/username/mcp-browser-agent
- Windowsの例:
C:\\Users\\username\\mcp-browser-agent
すでに他のMCPが設定されている場合は、「mcpServers」オブジェクト内に「browserAgent」セクションを追加するだけです。以下は、複数のMCPが設定された構成の例です。
{
"mcpServers": {
"otherMcp1": {
"command": "...",
"args": ["..."]
},
"otherMcp2": {
"command": "...",
"args": ["..."]
},
"browserAgent": {
"command": "node",
"args": [
"ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
"--browser",
"chrome"
]
}
}
}
🌐 ブラウザの選択
MCP Browser Agentは複数のブラウザタイプをサポートしています。デフォルトではChromeを使用しますが、いくつかの方法で別のブラウザを指定することができます。
オプション1: 設定ファイル
ホームディレクトリに.mcp_browser_agent_config.json
ファイルを作成または編集します。
{
"browserType": "chrome"
}
browserType
のサポートされる値は以下の通りです。
chrome
- インストールされたChromeを使用(デフォルト)
firefox
- Firefox 'Nightly'ブラウザを使用
webkit
- WebKitエンジンを使用(注: これはSafari自体ではなく、Safariを動作させるWebKitレンダリングエンジンです)
edge
- Microsoft Edgeを使用
Safariに関する注意: PlaywrightはSafariブラウザを直接サポートしていません。代わりに、Safariを動作させるブラウザエンジンであるWebKitを使用します。PlaywrightのWebKit実装は類似した機能を提供しますが、Safariブラウザのエクスペリエンスとは同一ではありません。
オプション2: コマンドライン引数
MCPサーバーを手動で起動するときに、ブラウザタイプを指定することができます。
node dist/index.js --browser firefox
オプション3: 環境変数
MCP_BROWSER_TYPE
環境変数を設定します。
MCP_BROWSER_TYPE=firefox node dist/index.js
オプション4: Claude Desktopの設定
Claude Desktopのclaude_desktop_config.json
でMCPを設定するときに、ブラウザタイプを指定することができます。
{
"mcpServers": {
"browserAgent": {
"command": "node",
"args": [
"ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
"--browser",
"chrome"
]
}
}
}
🔧 技術詳細
MCP Browser AgentはModel Context Protocolをベースに構築されており、ClaudeがPlaywrightを通じてヘッドフルブラウザとやり取りできるようにします。実装は以下の4つの主要なコンポーネントで構成されています。
-
サーバー (index.ts)
- Model Context Protocolの標準プロトコルでMCPサーバーを初期化する
- ツールとリソースのサーバー機能を構成する
- stdioトランスポートを通じてClaudeとの通信を確立する
-
ツールレジストリ (tools.ts)
- ブラウザとAPIツールのスキーマを定義する
- パラメータ、検証ルール、および説明を指定する
- Claudeが発見できるように、ツールをMCPサーバーに登録する
-
リクエストハンドラー (handlers.ts)
- ツールとリソースのMCPプロトコルリクエストを管理する
- ブラウザログとスクリーンショットをクエリ可能なリソースとして公開する
- ツール実行リクエストを適切なハンドラーにルーティングする
-
エグゼキューター (executor.ts)
- ブラウザとAPIクライアントのライフサイクルを管理する
- Playwrightを使用してブラウザ自動化機能を実装する
- 適切なエラーハンドリングとレスポンスパースでAPIリクエストを処理する
- コマンド間でステートフルなブラウザセッションを維持する
エージェント機能
基本的な統合とは異なり、MCP Browser Agentは以下のように真のAIエージェントとして機能します。
- 複数のコマンドにわたって永続的なブラウザ状態を維持する
- デバッグのために詳細なコンソールログをキャプチャする
- 参照とレビューのためにスクリーンショットを保存する
- 複雑なインタラクションシーケンスを管理する
- 回復のための詳細なエラー情報を提供する
- 複雑なワークフローのための連鎖操作をサポートする
🛠️ 利用可能なツール
ブラウザツール
ツール名 |
説明 |
パラメータ |
browser_navigate |
URLに移動する |
url (必須), timeout , waitUntil |
browser_screenshot |
スクリーンショットを撮影する |
name (必須), selector , fullPage , mask , savePath |
browser_click |
要素をクリックする |
selector (必須) |
browser_fill |
フォーム入力を行う |
selector (必須), value (必須) |
browser_select |
ドロップダウンオプションを選択する |
selector (必須), value (必須) |
browser_hover |
要素上にホバーする |
selector (必須) |
browser_evaluate |
JavaScriptを実行する |
script (必須) |
APIツール
ツール名 |
説明 |
パラメータ |
api_get |
GETリクエストを実行する |
url (必須), headers |
api_post |
POSTリクエストを実行する |
url (必須), data (必須), headers |
api_put |
PUTリクエストを実行する |
url (必須), data (必須), headers |
api_patch |
PATCHリクエストを実行する |
url (必須), data (必須), headers |
api_delete |
DELETEリクエストを実行する |
url (必須), headers |
📄 リソースアクセス
MCP Browser Agentは以下のリソースを公開しています。
browser://logs
- ブラウザコンソールログにアクセスする
screenshot://[name]
- 名前でスクリーンショットにアクセスする
💻 使用例
ClaudeでMCP Browser Agentを使用するいくつかの現実的な例を以下に示します。
基本的なブラウザナビゲーション
https://www.google.comのGoogleホームページに移動する
現在のページのスクリーンショットを撮影し、「google-homepage」と名付ける
検索ボックスに「weather forecast」と入力する
シンプルなインタラクション
https://www.wikipedia.orgに移動し、「Model Context Protocol」を検索する
https://the-internet.herokuapp.com/dropdownに移動し、ドロップダウンから「Option 1」を選択する
基本的なフォーム入力
https://the-internet.herokuapp.com/loginに移動し、ユーザー名フィールドに「tomsmith」、パスワードフィールドに「SuperSecretPassword!」を入力する
https://the-internet.herokuapp.com/loginに移動し、ユーザー名とパスワードフィールドに入力してから、ログインボタンをクリックする
シンプルなJavaScript実行
https://example.comに移動し、ページタイトルを返すJavaScriptスクリプトを実行する
https://www.google.comに移動し、ページ上のリンクの数をカウントするJavaScriptスクリプトを実行する
基本的なAPIリクエスト
https://jsonplaceholder.typicode.com/todos/1にGETリクエストを実行する
適切なJSONデータを含むhttps://jsonplaceholder.typicode.com/postsにPOSTリクエストを行う
これらの例は、MCP Browser Agentの実際の機能を表しており、現在の状態で達成できることをより現実的に示しています。
🐞 トラブルシューティング
"Server disconnected"エラー
Claude Desktopで「MCP Browser Agent: Server disconnected」エラーが表示された場合:
-
サーバーが実行中であることを確認する:
- ターミナルを開き、プロジェクトディレクトリから
node dist/index.js
を手動で実行します。
- サーバーが正常に起動した場合は、このターミナルを開いたままClaudeを使用します。
-
設定を確認する:
claude_desktop_config.json
の絶対パスがシステムに正しく設定されていることを確認します。
- Windowsパスにはダブルバックスラッシュ (
\\
) を使用していることを再確認します。
- ファイルシステムのルートからの完全なパスを使用していることを確認します。
ブラウザが表示されない場合
ブラウザが起動しないか、表示されない場合:
-
指定されたブラウザがインストールされていることを確認する
- システムにブラウザ(Chrome、Firefox、Edge、またはSafari/WebKit)がインストールされていることを確認します。
- ブラウザドライバはPlaywrightによって自動的に処理されます。
-
サーバーとClaude Desktopを再起動する
- サーバーを実行している可能性のある既存のノードプロセスをすべて終了します。
- Claude Desktopを再起動して、新しい接続を確立します。
ブラウザプロセスが適切に閉じられない場合
ChromiumとChromeブラウザには、使用後にプロセスが適切に終了しない既知の問題があります。この問題が発生した場合:
-
ブラウザプロセスを手動で閉じる:
- Windows: Ctrl+Shift+Escを押してタスクマネージャーを開き、Chrome/Chromiumプロセスを見つけて終了します。
- macOS: アクティビティモニター(アプリケーション > ユーティリティ > アクティビティモニター)を開き、Chrome/Chromiumプロセスを見つけてXをクリックして終了します。
- Linux:
ps aux | grep chrome
またはps aux | grep chromium
を実行してプロセスを見つけ、kill <PID>
で終了します。
-
ブラウザ互換性に関する注意:
- この問題は主にChromiumとChromeで観察されています。
- FirefoxとPlaywrightの組み込みブラウザでは通常、この問題は発生しません。
⚠️ 重要な注意
このMCP統合はPlaywrightをベースに構築されており、動作に影響を与える既知の問題やバグがあります。ブラウザ自動化に関する問題は、PlaywrightのGitHubイシューに報告してください。Playwrightチームはこれらの問題を解決するために継続的に取り組んでいますが、このエージェントはこれらの制限にもかかわらず、Claude Desktopでのブラウザ自動化機能の基礎を提供します。
🛠️ 開発
プロジェクト構造
src/index.ts
: メインエントリポイントとMCPサーバーの初期化
src/tools.ts
: ツールスキーマと登録
src/handlers.ts
: ツールとリソースのMCPリクエストハンドラー
src/executor.ts
: Playwrightを使用したツール実装ロジック
ビルド
npm run build
変更の監視
npm run watch
🧪 テスト
このプロジェクトには、コア機能とブラウザ処理を検証するテストが含まれています。
npm test # テストを実行する
npm run test:watch # ウォッチモード
npm run test:coverage # カバレッジレポート
テストでは、設定の整合性、ブラウザ自動化機能、エラーハンドリング、およびプロセスのクリーンアップを検証します。テストスイートは、Chrome/Chromiumの終了に関する既知の問題のため、特にブラウザプロセスの適切な処理を確保することに焦点を当てています。
🔒 セキュリティに関する考慮事項
⚠️ 重要な注意
このMCP統合はClaudeに自動化されたブラウザ制御機能を提供します。禁止された使用方法、セキュリティ上の影響、およびベストプラクティスに関する重要な情報については、セキュリティポリシーを確認してください。
MCP Browser Agentは正当な自動化タスクを目的として設計されていますが、悪用される可能性があります。ユーザーは、すべての適用される法律、サービス利用規約、および倫理ガイドラインに準拠した使用を確保する責任があります。詳細については、セキュリティポリシーを参照してください。
🤝 コントリビューション
MCP Browser Agentへのコントリビューションは歓迎されます!以下の分野でご協力いただけます。
- 新しいブラウザ自動化機能の追加
- エラーハンドリングと回復の改善
- スクリーンショットとリソース管理の強化
- 有用なワークフローと例の作成
- 複雑な操作のパフォーマンスの最適化
📄 ライセンス
このプロジェクトはMozilla Public License 2.0の下でライセンスされています。詳細については、LICENSEファイルを参照してください。
🔗 関連リンク