ブラウザエージェントMCP

MCP ブラウザエージェント

特徴

高度なブラウザ自動化
- カスタマイズ可能なロード戦略で任意の 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がWebページからビジュアルコンテンツをキャプチャして保存する方法を紹介します。

01:00 - Wikipedia検索
Wikipedia.org にアクセスし、「Model Context Protocol」を検索します。Claude が MCP 統合を通じてさまざまなウェブサイトやその検索機能とやり取りする様子を示します。

01:38 -ドロップダウンメニューインタラクション I
テストウェブサイト（the-internet.herokuapp.com/dropdown）に移動し、ドロップダウンメニューから「オプション1」を選択します。Claudeがフォーム要素を操作して選択する能力を示します。

01:56 -ドロップダウンメニューインタラクション II
同じドロップダウンメニューから「オプション2」を選択に変更します。Claude が同じフォーム要素を複数回操作し、異なる選択を行う能力を示しています。

02:09 -ログインフォームの完了
ログインページ（the-internet.herokuapp.com/login）に移動し、ユーザー名フィールドに「tomsmith」、パスワードフィー��ドに「SuperSecretPassword!」を入力します。フォーム入力の自動化のデモです。

02:28 -ログイン送信
ログイン資格情報を送信し、認証プロセスを完了します。Claude がフォームの送信をトリガーし、複数のステップからなるプロセスをナビゲートする能力を示します。

02:36 - APIリクエストの実行
JSONPlaceholder APIエンドポイントへのGETリクエストを実行します。Claudeが直接API呼び出しを行い、MCP統合を通じて返されたデータを処理できる能力を示します。

要件

Node.js 16以上
クロードデスクトップ
Playwrightの依存関係

ブラウザのサポート

npm init playwright@latest

このパッケージには、Playwrightとブラウザ自動化の実行に必要な依存関係が含まれています。npm npm install実行すると、必要なPlaywrightの依存関係がインストールされます。このパッケージは以下のブラウザをサポートしています。

Chrome（デフォルト）
ファイアフォックス
マイクロソフトエッジ
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を選択した場合、エージェントは実際にはChromiumではなくMicrosoft Edgeを起動します。技術的には、Playwrightでは、Microsoft EdgeはChromiumをベースにしているため、Chromiumブラウザインスタンスと「msedge」チャネルパラメータを使用してEdgeが起動されます。

インストール

手動でインストールする

このリポジトリをクローンまたはダウンロードします:

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

このファイルを編集して、ブラウザエージェント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ブラウザエージェントは複数のブラウザタイプをサポートしています。デフォルトでは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ブラウザと同様の機能を提供しますが、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_config.jsonで MCP を構成するときに、ブラウザの種類を指定できます。

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
        "--browser",
        "chrome"
      ]
    }
  }
}

技術的実装

MCPブラウザエージェントはモデルコンテキストプロトコル（MCP）上に構築されており、ClaudeがPlaywrightを介してヘッドフルブラウザと対話することを可能にします。実装は4つの主要コンポーネントで構成されています。

サーバー (index.ts)
- モデルコンテキストプロトコル標準プロトコルを使用してMCPサーバーを初期化します
- ツールとリソースのサーバー機能を構成します
- stdioトランスポートを介してClaudeとの通信を確立する
ツールレジストリ (tools.ts)
- ブラウザとAPIツールのスキーマを定義します
- パラメータ、検証ルール、説明を指定します
- クロードの発見のためにMCPサーバーにツールを登録する
リクエストハンドラー (handlers.ts)
- ツールとリソースのMCPプロトコル要求を管理します
- ブラウザのログとスクリーンショットをクエリ可能なリソースとして公開します
- ツール実行リクエストを適切なハンドラーにルーティングします
エグゼキュータ (executor.ts)
- ブラウザとAPIクライアントのライフサイクルを管理します
- Playwrightを使用してブラウザ自動化機能を実装します
- 適切なエラー処理とレスポンス解析でAPIリクエストを処理する
- コマンド間のステートフルなブラウザセッションを維持する

エージェントの機能

基本的な統合とは異なり、MCP ブラウザエージェントは次の方法で真の 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`	削除リクエスト	`url` （必須）、 `headers`

リソースアクセス

MCP ブラウザエージェントは次のリソースを公開します。

browser://logs - ブラウザコンソールのログにアクセスする
screenshot://[name] - 名前でスクリーンショットにアクセスします

使用例

Claude で MCP ブラウザエージェントを使用する実際の例をいくつか示します。

基本的なブラウザナビゲーション

Navigate to the Google homepage at https://www.google.com

Take a screenshot of the current page and name it "google-homepage"

Type "weather forecast" in the search box

シンプルなインタラクション

Navigate to https://www.wikipedia.org and search for "Model Context Protocol"

Go to https://the-internet.herokuapp.com/dropdown and select the option "Option 1" from the dropdown

基本的なフォーム入力

Navigate to https://the-internet.herokuapp.com/login and fill in the username field with "tomsmith" and the password field with "SuperSecretPassword!"

Go to https://the-internet.herokuapp.com/login, fill in the username and password fields, then click the login button

シンプルなJavaScript実行

Go to https://example.com and execute a JavaScript script to return the page title

Navigate to https://www.google.com and execute a JavaScript script to count the number of links on the page

基本的なAPIリクエスト

Perform a GET request to https://jsonplaceholder.typicode.com/todos/1

Make a POST request to https://jsonplaceholder.typicode.com/posts with appropriate JSON data

これらの例は、MCP ブラウザエージェントの実際の機能を表し、現在の状態で何が達成できるかをより現実的に示しています。

トラブルシューティング

「サーバーが切断されました」エラー

Claude Desktop で「MCP ブラウザエージェント: サーバーが切断されました」というエラーが表示される場合:

サーバーが実行中であることを確認します:
- ターミナルを開き、プロジェクトディレクトリから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には動作に影響を与える可能性のある既知の問題やバグがあります。ブラウザ自動化で問題が発生した場合は、PlaywrightのGitHub issuesまでご報告ください。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               # Run tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

テストでは、設定の整合性、ブラウザ自動化機能、エラー処理、プロセスのクリーンアップを検証します。テストスイートは、Chrome/Chromiumの終了に関する既知の問題を考慮し、ブラウザプロセスの適切な処理に特に重点を置いています。

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

[!重要] このMCP統合により、Claudeは自律的なブラウザ制御機能を利用できるようになります。禁止事項、セキュリティへの影響、ベストプラクティスに関する重要な情報については、セキュリティポリシーをご確認ください。

MCPブラウザエージェントは正当な自動化タスクのために設計されていますが、悪用される可能性があります。ユーザーは、適用されるすべての法律、利用規約、および倫理ガイドラインを遵守して使用する責任を負います。詳細については、詳細なセキュリティポリシーをご覧ください。

貢献

MCP ブラウザエージェントへの貢献を歓迎します！貢献できる分野は以下のとおりです。

新しいブラウザ自動化機能の追加
エラー処理と回復の改善
スクリーンショットとリソース管理の強化
便利なワークフローと例を作成する
複雑な操作のパフォーマンスの最適化

ライセンス

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