MCP Browser

✅ MCPBrowser（MCP Browser）

⚠️ セキュリティに関する注意： MCPBrowser はウェブページのコンテンツを抽出し、AI エージェント（GitHub Copilot、Claude、Kiro、Antigravity など）に渡します。その後、エージェントは処理のために、使用している LLM プロバイダー（Anthropic、OpenAI、GitHub など）へコンテンツを送信します。エージェントと LLM プロバイダーの両方を信頼できることを確認してください。特に、機密データや非公開データを含むページにアクセスする場合はご注意ください。MCPBrowser は、プライベートデータへのアクセス、信頼できないコンテンツへの接触、外部との通信（MCP の「致命的な三要素」）を組み合わせています。すべてのツールアノテーションでこれらのリスクを正確に明示しているため、MCP クライアントは適切な安全制御を適用できます。詳しくは MCP_COMPLIANCE.md をご覧ください。

💡 Puppeteer／Playwright の MCP サーバーではなく、MCPBrowser を選ぶ理由は？ Puppeteer と Playwright はブラウザー自動化ライブラリであり、それらの MCP サーバーはエージェントに低レベルのブラウザーコマンドを直接提供します。MCPBrowser は内部で Puppeteer を使用し、AI エージェント専用に構築されています。難しい処理を自動で行うインテリジェンス層を追加しています。

エージェントは、クリーンな HTML（90％小さい）、SPA の自動検出（React、Vue、Angular）、認証フローの処理（SSO、リダイレクト、複数ステップのログイン）、複数フィールドへの入力を含むフォームの検出、次のステップのガイダンスを含む構造化された応答、ドメインベースのタブ再利用、ページを再読み込みしない即時の DOM 再抽出を利用できます。MCPBrowser の各ツール呼び出しで、ブラウザー自動化の生の呼び出しを 5～8 回置き換えられます。MCPBrowser で通常 4 ステップのワークフローを実行する場合、Puppeteer／Playwright MCP では 20 回以上の呼び出しが必要となるため、トークンを節約し、エージェントの動作を大幅に高速化できます。以下の詳しい比較をご覧ください。

MCPBrowser は、実際の Chrome、Edge、または Brave ブラウザーを使ってウェブページを閲覧する機能を AI アシスタントに提供する、MCP ブラウザーサーバーです。 このブラウザーベースの MCP サーバーは、認証、CAPTCHA、ボット対策によって保護されているページや、JavaScript のレンダリングが必要なページを特に含め、あらゆるウェブページを取得します。実際のブラウザーを使ってウェブ自動化を行うため、通常どおりログインすると、コンテンツが自動的に抽出されます。企業の SSO、ログインフォーム、Cloudflare、JavaScript を多用するサイト（SPA、ダッシュボード）で動作します。

これは stdio トランスポートを使用する MCP（Model Context Protocol） サーバーです。標準的な HTTP リクエストでは失敗する場合、たとえば認証、CAPTCHA による保護、または大量の JavaScript（SPA）が必要なページで、AI アシスタントはこのウェブブラウザー MCP サーバーを使用します。接続すると、ブラウザー MCP サーバーはウェブサイトを移動し、要素を操作して、HTML を AI アシスタントに返すことができます。これにより、AI はユーザーと同じようにウェブを閲覧できます。

AI アシスタントが MCPBrowser を使用するワークフローの例

1. browser_fetch_webpage    → Load the login page
2. browser_type_text        → Enter username and password (multiple fields at once)
3. browser_click_element    → Click "Sign In"
4. browser_get_current_html → Extract the content after login

Puppeteer／Playwright MCP サーバーではなくMCPBrowserを選ぶ理由

PuppeteerとPlaywrightはブラウザー自動化ライブラリです。これらのMCPサーバーは低レベルのブラウザーコマンドを公開しており、エージェントはSPA、認証フロー、扱いにくいHTML、エッジケースを自力で処理する必要があります。**MCPBrowserはAIエージェント向けに特化して構築されています。**内部でPuppeteerを使用し、インテリジェンス層を追加することで、エージェントはブラウザーへの対処ではなくタスクに集中できます。

	MCPBrowser	Puppeteer/Playwright MCP
HTML出力	クリーンでLLMに最適化（約90％小容量）—スクリプト、スタイル、SVG、トラッキング属性を除去し、相対URLを変換します	生のDOM
SPA対応	React、Vue、Angular、Svelte、Next.js、Nuxtを自動検出し、フレームワークに対応した待機戦略を適用します	エージェントが待機を手動で設定する必要があります
認証	ログインページ、SSOリダイレクト、複数ステップの認証を検出し、リダイレクトチェーンと2段階のタイムアウト（SSOは5秒→手動操作は20分）に対応します	エージェントが認証の各ステップをスクリプトで記述する必要があります
フォーム操作	browser_detect_formsですべてのフィールド、ラベル、制約を検出し、browser_type_textで複数のフィールドに一度に入力します	1フィールドずつ、セレクターを手動で指定
レスポンス形式	nextStepsのガイダンス付きで型付けされた構造化形式—ソフト失敗とハード失敗を区別し、復旧アクションを提示します	生の結果、一般的なエラー
タブ管理	ドメインごとにプール化—タブを再利用し、ブラウザー再接続後も維持します	リクエストごとに新しいコンテキスト
DOMの再抽出	browser_get_current_html—再読み込み不要ですぐに実行（10～50倍高速）	ページ全体を再取得する必要があります
プラグインシステム	URL／DOMパターンで既知のサイトを検出し、信頼度スコア付きでサイト固有のアクションを提示します	該当なし
用途	AIエージェント	ブラウザーテストの自動化
エージェントの効率	1回のツール呼び出しで生のブラウザー呼び出し5～8回分を置き換えます。4ステップのログインフローは20回以上ではなく4回の呼び出しで完了し、トークンと往復を節約できます	各ステップ（移動、待機、検索、入力、クリック）が個別の呼び出しです

目次

• Puppeteer／Playwright の MCP サーバーではなく MCPBrowser を選ぶ理由
• 要件
• インストール
  • VS Code 拡張機能
  • Claude Code
  • Claude Desktop
  • npm パッケージ
• MCP ツール
  • browser_fetch_webpage
  • browser_execute_javascript
  • browser_click_element
  • browser_type_text
  • browser_get_current_html
  • browser_scroll_page
  • browser_take_screenshot
  • browser_close_tab
• Microsoft Word Online プラグイン
• アクションの開発
• CLI モード
• 設定（任意）
• トラブルシューティング
• リンク

要件

• Chrome、Edge、または Brave ブラウザー
• Node.js 18+（npm を含む）

注： Node.js をシステムにインストールする必要があります。VS Code 拡張機能と npm パッケージのどちらも、MCP サーバーの実行に Node.js が必要です。まだインストールされていない場合は、nodejs.org からダウンロードしてください。

インストール

#	プラットフォーム	難易度
1	VS Code 拡張機能	ワンクリック
2	Claude Code	コマンド 1 つ
3	OpenClaw	コマンド 1 つ
4	Claude Desktop	手動
5	npm パッケージ	手動

オプション 1：VS Code 拡張機能

VS Code Marketplace または Open VSX Registry からインストールするか、次のコマンドを実行してください。

code --install-extension cherchyk.mcpbrowser

この拡張機能は、AI エージェント（GitHub Copilot、Kiro Agent、Antigravity Agent）に必要なものをすべて自動でインストールし、設定します。VSCodium や、Open VSX 互換のその他のエディターでも動作します。

オプション 2：Claude Code

claude mcp add mcpbrowser --scope user -- npx -y mcpbrowser@latest

動作を確認します。

claude mcp list

次のように表示されます。

mcpbrowser: npx -y mcpbrowser@latest - ✓ Connected

これで完了です。Claude に、保護されたページを取得するよう依頼してみてください。

「mcpbrowser を使って https://portal.azure.com を取得して」

オプション 3：OpenClaw

OpenClaw は、お使いのデバイス上で動作するパーソナル AI アシスタントです。MCPBrowser を追加すると、ブラウザーの自動操作機能を利用できます。

openclaw mcp add mcpbrowser -- npx -y mcpbrowser@latest

動作を確認します。

openclaw mcp list

これで OpenClaw は、既存のブラウザーセッションを使用して、認証が必要なページの閲覧、フォームへの入力、Web アプリの操作ができるようになります。

オプション 4：Claude Desktop

設定ファイルに追加します（存在しない場合は作成してください）。

Windows： %APPDATA%\Claude\claude_desktop_config.json（例：C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json）
Mac： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "MCPBrowser": {
      "command": "npx",
      "args": ["-y", "mcpbrowser@latest"]
    }
  }
}

保存後、Claude Desktop を再起動してください。

オプション 5：npm パッケージ

VS Code、Kiro、Antigravity、その他のエディター向けの手動 MCP 設定です。mcp.json に追加してください。

Windows： %APPDATA%\Code\User\mcp.json Mac/Linux： ~/.config/Code/User/mcp.json

{
  "servers": {
    "MCPBrowser": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcpbrowser@latest"]
    }
  }
}

MCP ツール

browser_fetch_webpage

Chrome／Edge／Brave ブラウザーを使用してウェブページを取得します。認証、CAPTCHA、SSO、ボット対策、JavaScript を多用するサイトに対応しています。URL をブラウザーのタブで開き（同じドメインの既存のタブがあれば再利用します）、ページが完全に読み込まれるまで待ってからコンテンツを返します。SPA（React、Vue、Angular）を自動検出し、JavaScript によるコンテンツの描画を待ちます。

パラメーター：

• url（string、必須）- 取得する URL
• removeUnnecessaryHTML（boolean、任意、デフォルト：true）- 不要な HTML を削除し、サイズを約 90％削減します
• postLoadWait（number、任意、デフォルト：0）- ページの読み込み後、HTML を抽出するまでに追加で待機するミリ秒数です。描画に時間がかかるページで使用します。

使用例：

// Basic fetch
{ url: "https://example.com" }

// Fetch with extra wait time for slow-rendering pages
{ url: "https://dashboard.example.com", postLoadWait: 2000 }

// Keep full HTML without cleanup
{ url: "https://example.com", removeUnnecessaryHTML: false }

---

browser_execute_javascript

アクティブなページのコンテキストで JavaScript スニペットを実行し、メタデータ（実行時間、切り詰められたかどうかのフラグ、URL 変更フラグ）とともに結果を返します。構造化データの抽出（受信トレイの行など）や、プロトコル経由のクリックでは安定して実行できない、JavaScript による UI 操作に使用します。

⚠️ 注意： 先に browser_fetch_webpage でページを読み込んでおく必要があります。

パラメーター：

• url（string、必須）- ページの URL（以前に取得したページと一致している必要があります）
• script（string、必須）- ページのコンテキストで実行する JavaScript ソース
• timeoutMs（number、任意、デフォルト：30000、最大：60000）- 実行タイムアウト
• returnType（string、任意、デフォルト：json）- json | text | void

戻り値： シリアライズされた結果（DOM ノードの場合は outerHTML）、type、executionTimeMs、truncated、urlChanged、currentUrl、およびスクリプトの例外発生時やタイムアウト時の構造化された error。

使用例：

{
  "action": "browser_execute_javascript",
  "url": "https://mail.google.com/",
  "script": "[...document.querySelectorAll('tr.zA')].slice(0,5).map((row,i)=>({index:i+1,sender:row.querySelector('.zF,.yP')?.textContent,subject:row.querySelector('.bog')?.textContent}))",
  "timeoutMs": 30000,
  "returnType": "json"
}

---

browser_click_element

ボタン、リンク、onclick ハンドラーを持つ div など、クリック可能な要素をクリックします。CSS セレクターまたは表示テキストで対象を指定できます。要素が表示される位置まで自動的にスクロールし、クリック後にページが安定するまで待機します。

⚠️ 注意： 先に browser_fetch_webpage でページを読み込んでおく必要があります。

パラメーター：

• url（string、必須）- ページの URL（以前に取得したページと一致している必要があります）
• selector（string、任意）- 要素の CSS セレクター（例：#submit-btn、.login-button）
• text（string、任意）- セレクターが指定されていない場合に検索するテキスト（例：「Sign In」、「Submit」）
• returnHtml（boolean、任意、デフォルト：true）- クリック後に安定するまで待機し、HTML を返すかどうか。チェックボックスやラジオボタンなど、フォームをすばやく操作する場合は false に設定します
• removeUnnecessaryHTML（boolean、任意、デフォルト：true）- 不要な HTML を削除してサイズを削減します。returnHtml が true の場合にのみ使用されます
• postClickWait（number、任意、デフォルト：1000）- クリック後、SPA が動的コンテンツを描画するまで待機するミリ秒数
• waitForElementTimeout（number、任意、デフォルト：1000）- 要素を待つ最大時間（ミリ秒）

使用例：

// Click by text content
{ url: "https://example.com", text: "Sign In" }

// Click by CSS selector
{ url: "https://example.com", selector: "#login-button" }

// Click without waiting for HTML (fast checkbox toggle)
{ url: "https://example.com", selector: "#agree-checkbox", returnHtml: false }

// Click with custom wait time
{ url: "https://example.com", text: "Load More", postClickWait: 2000 }

フォールバック動作： 要素を特定した後にネイティブクリックがタイムアウトすると、MCPBrowser は JavaScript によるクリックを自動的に再試行し、fallbackUsed、nativeAttempt、fallbackAttempt のメタデータを返します。両方の試行が失敗した場合は、別の方法を選べるよう、両方のエラーがレスポンスに含まれます。

---

browser_type_text

1 回の呼び出しで、1 つ以上の入力フィールドにテキストを入力します。効率的な自動化のため、フォーム全体を一度に入力できます。デフォルトでは、既存のテキストを自動的に消去します。

⚠️ 注意： 最初に browser_fetch_webpage でページを読み込んでおく必要があります。

パラメーター：

• url（string、必須）- ページの URL（以前に取得したページと一致する必要があります）
• fields（array、必須）- 入力するフィールドの配列。各フィールドオブジェクトには、次の項目が含まれます。
  • selector（string、必須）- 入力要素の CSS セレクター（例：#username、input[name="email"]）
  • text（string、必須）- フィールドに入力するテキスト
  • clear（boolean、任意、デフォルト：true）- 最初に既存のテキストを消去するかどうか
  • waitForElementTimeout（number、任意、デフォルト：5000）- 要素を待機する最大時間（ミリ秒）
• returnHtml（boolean、任意、デフォルト：true）- 入力後、安定するまで待機して HTML を返すかどうか
• removeUnnecessaryHTML（boolean、任意、デフォルト：true）- サイズ削減のために不要な HTML を削除します。returnHtml が true の場合のみ使用されます
• postTypeWait（number、任意、デフォルト：1000）- 入力後、SPA が動的コンテンツを描画するまで待機する時間（ミリ秒）

例：

// Fill multiple fields at once (login form)
{
  url: "https://example.com/login",
  fields: [
    { selector: "#username", text: "[email protected]" },
    { selector: "#password", text: "secretpass123" }
  ]
}

// Single field input
{ url: "https://example.com", fields: [{ selector: "#search", text: "query" }] }

// Append text without clearing
{ url: "https://example.com", fields: [{ selector: "#notes", text: " additional text", clear: false }] }

// Fast form fill without HTML return
{
  url: "https://example.com/signup",
  fields: [
    { selector: "#firstName", text: "John" },
    { selector: "#lastName", text: "Doe" },
    { selector: "#email", text: "[email protected]" }
  ],
  returnHtml: false
}

エラー処理： フィールドの入力に失敗した場合、レスポンスには次の情報が示されます。

• 失敗したフィールドの番号（例：「3 件中 2 件目のフィールドで失敗しました」）
• 正常に入力されたフィールド
• 入力済みのフィールドに再入力しないようにするための明確な指示

---

browser_get_current_html

移動や再読み込みをせずに、すでに読み込まれているページから現在の HTML を取得します。現在の DOM の状態だけを抽出するため、browser_fetch_webpage よりも大幅に高速です。操作（クリック、入力）後に使用すると、更新されたページのコンテンツを効率的に取得できます。

⚠️ 注意： 最初に browser_fetch_webpage でページを読み込んでおく必要があります。

パラメーター：

• url（string、必須）- ページの URL（以前に取得したページと一致する必要があります）
• removeUnnecessaryHTML（boolean、任意、デフォルト：true）- サイズを約 90％削減するために不要な HTML を削除します

例：

// Get current HTML after interactions
{ url: "https://example.com" }

// Get full HTML without cleanup
{ url: "https://example.com", removeUnnecessaryHTML: false }

パフォーマンスの比較：

• browser_fetch_webpage：2～5 秒（ページ全体を再読み込み）
• browser_get_current_html：0.1～0.3 秒（HTML の抽出のみ）✅

---

browser_scroll_page

すでに読み込まれているページ内をスクロールします。ページの異なる部分をキャプチャするには browser_take_screenshot の前に、操作前に要素を表示するにはその前に使用します。複数のスクロールモードに対応しています。

• 方向を指定：指定したピクセル数だけ上下左右にスクロールします
• 要素を指定：特定の要素が表示されるまでスクロールします
• 位置を指定：絶対座標までスクロールします

⚠️ 注意： 最初に browser_fetch_webpage でページを読み込んでおく必要があります。

パラメーター：

• url（string、必須）- ページの URL（以前に取得したページと一致する必要があります）
• direction（string、任意）- スクロールする方向：up、down、left、right。amount と併用します。
• amount（number、任意、デフォルト：500）- 指定した方向にスクロールするピクセル数（ビューポートの約半分）
• selector（string、任意）- 表示範囲内にスクロールする要素の CSS セレクター。direction と amount は無視されます。
• x（number、任意）- 水平方向の絶対スクロール位置。y と併用します。
• y（number、任意）- 垂直方向の絶対スクロール位置。x と併用します。

例：

// Scroll down by 500px (default)
{ url: "https://example.com", direction: "down" }

// Scroll down by 1000px
{ url: "https://example.com", direction: "down", amount: 1000 }

// Scroll an element into view
{ url: "https://example.com", selector: "#footer" }

// Scroll to specific position
{ url: "https://example.com", x: 0, y: 2000 }

// Scroll to top of page
{ url: "https://example.com", x: 0, y: 0 }

返される情報： 現在のスクロール位置、ページの寸法、ビューポートのサイズ。ページ内の現在位置を把握するのに役立ちます。

---

browser_take_screenshot

視覚的な分析のために、読み込み済みのページのスクリーンショットを撮影します。HTML の解析だけでは不十分な場合に便利です。たとえば、グラフ、画像、複雑なレイアウト、ポップアップ、HTML だけでは把握しにくい視覚的なコンテンツを含むページなどが該当します。PNG 画像を返します。

⚠️ 注意： 事前に browser_fetch_webpage でページを読み込んでおく必要があります。

パラメーター：

• url（文字列、必須）- ページの URL（以前に取得したページと一致している必要があります）
• fullPage（ブール値、任意、デフォルト：false）- ビューポートのみではなく、スクロール可能なページ全体をキャプチャします

例：

// Capture viewport screenshot (default)
{ url: "https://example.com" }

// Capture full scrollable page
{ url: "https://dashboard.example.com", fullPage: true }

ユースケース：

• HTML の解析が難しい場合にページのレイアウトを視覚的に確認する
• グラフ、図表、データの可視化をキャプチャする
• ポップアップ、モーダル、オーバーレイをデバッグする
• 視覚的なフィードバック（ハイライト、アニメーション）を把握する
• 要素のクリックを妨げているものを確認する

---

browser_close_tab

指定された URL のホスト名に対応するブラウザータブを閉じます。ページをタブプールから削除し、そのホスト名に次回アクセスしたときに新しいセッションを開始します。認証状態のクリア、メモリの管理、またはドメインで新たに作業を始める場合に便利です。

⚠️ 注意： ホスト名は完全一致で判定されます（www.example.com と example.com は別のタブとして扱われます）。

パラメーター：

• url（文字列、必須）- ホスト名に対応するタブを閉じる URL

例：

// Close tab for a domain
{
  url: 'https://example.com';
}

// This will close the tab for portal.azure.com
{
  url: 'https://portal.azure.com/dashboard';
}

ユースケース：

• 認証／セッション状態をクリアする
• ブラウザーのメモリを解放する
• 新たにログインする前に状態をリセットする

Microsoft Word Online プラグイン

有効化された word プラグインは、SharePoint または OneDrive でホストされている、認証済みの Word Online ドキュメントのコンテンツを読み取り、置き換えます。browser_fetch_webpage でドキュメントを開いてから、browser_plugin_info と browser_plugin_action を使ってアクションを確認または実行してください。

アクション	目的
open_document	ドキュメントの URL を開き、SharePoint 上のエディターを安全に前面へ表示して、編集／表示モードを確認します
read_document	上限付きのレンダリング済みドキュメントテキストと構造メタデータを返します
replace_document_text	ドキュメント全体をプレーンテキストで置き換えます
replace_document_html	サニタイズ済みリッチ HTML とプレーンテキストのフォールバックでドキュメント全体を置き換えます
insert_document_text	既存の内容を置き換えずに、プレーンテキストを先頭または末尾に挿入します
insert_document_html	既存の内容を置き換えずに、サニタイズ済みリッチ HTML を先頭または末尾に挿入します
import_markdown	ローカルの Markdown ファイルと画像を絶対ファイルパスでインポートします
export_markdown	ドキュメント全体をローカルの Markdown パスと同階層の画像フォルダーにエクスポートします
find_text	大文字と小文字の区別、および単語単位の一致を任意で指定して、ドキュメント全体を検索します
replace_text	Word のネイティブなドキュメントモデルを使って、1 件またはすべての一致箇所を正確に置き換えます
get_document_info	タイトル、モード、単語数、レンダリング済みレイアウト、保存状態を読み取ります
get_outline	Word のネイティブな見出しアウトラインを読み取ります
read_range	見出しに移動して、レンダリング済みの段落範囲を読み取ります
get_text_context	1 件の一致箇所について、ネイティブな検索コンテキストを確認します
insert_at	正確に一致する箇所の前または後にテキストを挿入します
replace_range / delete_range	位置指定された1件の一致箇所を置き換える、または削除します
format_range	位置指定されたテキストに太字、斜体、下線、または取り消し線を適用します
list_tables / read_table / update_table_cell	レンダリング済みの表を確認し、安全に更新します
list_links / add_link / update_link / remove_link	レンダリング済みのハイパーリンクを確認し、編集します
list_comments / add_comment / resolve_comment	Word のコメントを操作します
get_state	エディターモード、レイアウトの件数、上限付きのテキストチェック、Word の保存シグナルを報告します
wait_for_save	安定したレイアウト、任意の接頭辞／接尾辞の一致、および Word による Saved 状態の確認を必須にします
close_document	保存を確認してから、Word のタブを閉じます
サポートされるエントリーポイントには、https://word.cloud.microsoft/、HTTPS の SharePoint／OneDrive の Word リンク、*.officeapps.live.com 配下の Word エディターのホストが含まれます。プラグインは既存のブラウザーセッションを使用します。サインイン、MFA、または同意の手続きは、ブラウザーで直接完了してください。

リッチ HTML の更新では、送信前にアクティブコンテンツ、イベントハンドラー、埋め込みリソース、フォーム、画像、安全でない URL スキームを削除します。画像については import_markdown が例外です。このアクションは、Markdown が参照するサポート対象のローカル画像ファイルを読み込み、種類とサイズを検証したうえで、制限付きの Word クリップボード操作を通じて埋め込みます。Markdown 入力内のリモート画像とデータ URL 画像は拒否されます。ソースと検証用コンテンツはメモリ内で処理され、変更アクションから返されることはありません。このプラグインは SharePoint の WOPI アクセストークン、Cookie、認可ヘッダーを公開しません。

絶対パスの sourcePath と、replace、start、end のいずれかの placement を指定して import_markdown を使用します。大きなドキュメントは、MCP リクエストで一度に送信せず、Markdown のブロック境界で分割されます。絶対パスの outputPath を指定して export_markdown を使用します。たとえば D:\docs\guide.md の場合、抽出された画像は D:\docs\guide.assets\ に書き込まれ、Word が提供した名前がある場合はその名前が保持されます。このアクションは、エクスポートされたコンテンツではなく、パス、件数、未解決画像のメタデータを返します。overwrite が true でない限り、既存の Markdown ファイルは置き換えられません。

インポート、およびドキュメント全体のテキスト／HTML の編集では、ネイティブのキーボード操作を使用し、成功を報告したり次のチャンクを挿入したりする前に、Word のドキュメント全体のクリップボードテキストと期待される結果を比較します。replace_text、replace_range、delete_range およびそれらを呼び出すテーブル／アンカーテキスト操作でも、無関係なコンテンツを保持しながら期待されるテキストを検証します。貼り付けイベントの確認応答や［置換］ボタンのクリックは、変更が行われた証拠にはなりません。検証では、一時的に利用できないクリップボードの読み取りを再試行し、期待されるドキュメントサイズに応じて、上限付きのクリップボード待機時間とポーリング待機時間を調整し、レイアウト上の空白を正規化します。ただし、リッチ書式、画像の忠実度、コメントのアンカー、永続化を保証するものではありません。組み込みの標準スタイル／見出しスタイルとリッチコンテンツは個別に確認し、その後 wait_for_save を使用してください。ドキュメント全体のテキストをコピーできない場合、これらの編集は実行されず、可能な場合は最後にクリップボードの読み取りが失敗した理由が報告されます。

検証できなかった変更は、ドキュメントが変更されなかったと断言せず、結果不明として報告されます。インポートが部分的に行われた場合は、停止したチャンクと、結果のテキストが検証されたチャンク数が示されます。エラーや MCP タイムアウトの後に、自動的に再試行または追記しないでください。まず対象のコンテンツと保存状態を確認してください。自動再開とセッションをまたいだ操作追跡には対応していません。

Word のアクションは順番に実行してください。1 つのサーバープロセス内では、フォーカス移動、移動、テキスト選択を伴う読み取りも含め、Word プラグインのアクションが並行して実行されるとビジー状態として拒否されます。呼び出し元がタイムアウトしても、実行中のアクションが完了するまでガードは保持されます。別々の MCPBrowser プロセス、汎用ブラウザーツール、人間や共同編集者による入力は、このガードの対象外です。同じドキュメントを同時に編集しないでください。

read_document は、分割読み込み用に offset と maxCharacters をサポートします。Word が現在描画しているページを反映し、大きなドキュメントでは Word が仮想化を行うため、mayBePartial: true を報告します。Word の保存インジケーターを利用できない場合、wait_for_save は永続化されたと仮定せず、失敗します。

大きなドキュメントでは、ファイルを読み込んで再構築するより、find_text と replace_text を優先してください。replace_text は影響を受けないコンテンツと書式を保持し、1 始まりの出現番号または replaceAll をサポートします。また、expectedMatchCount を指定すると、曖昧な編集や古くなった編集がドキュメントを変更せずに失敗するようにできます。 「Markdown の変更に従って Word を更新する」場合は、実際に変更されたテキストを対象に置換し、できれば expectedMatchCount: 1 を指定してください。ユーザーが本文全体の置換を明示的に希望している場合を除き、placement: replace を指定した import_markdown は使用しないでください。Markdown の自動マージやベースライン管理のワークフローはありません。ソースファイルに合わせるためだけに、独立して行われた Word の編集を上書きしてはいけません。競合は報告してください。ネイティブの対象指定編集では、関係のないコンテンツはそのまま残りますが、編集前に、変更または削除されるテキストに付いているレビューコメントを確認してください。それらのアンカーでコメントが保持される保証はありません。

表とリンクの列挙は、Word が大きなドキュメントを仮想化するため、現在レンダリングされているページに限られます。まず get_outline、read_range、または find_text を使って該当箇所に移動してください。ロケーターが曖昧な場合は、出現箇所または期待される一致数を指定しないと、アンカー付きの変更処理は失敗します。

アクションの開発

すべてのアクションは、src/core/actions.js の共通コントラクトを使用します。tool にはメタデータとスキーマ、response には成功時の MCPResponse 型、handler には実装が含まれます。呼び出し元は execute() を呼び出し、MCPResponse 以外を返すハンドラーは拒否されます。各 actions/ フォルダーには、そのフォルダーの ACTIONS 配列全体をエクスポートする index.js があります。登録コードはアクション一覧を再構築せず、この配列を使用します。

各アクションモジュールの公開エクスポートは、CoreAction または PluginAction の記述子だけです。ツールスキーマ、レスポンスクラス、ハンドラーは非公開のままで、記述子の tool、response、handler プロパティから利用できます。各記述子には、tool.name と同じ値を持つ不変の id もあります。これにより、呼び出し元やテストはフォルダーの ACTIONS 配列から該当するアクションを選択できます。

export const FETCH_WEBPAGE_ACTION = new CoreAction({
  tool: FETCH_WEBPAGE_TOOL,
  response: FetchPageSuccessResponse,
  handler: fetchPage,
});

コアアクションには cli オブジェクトを追加して CLI に対応させることができます。また、1 つのアクションに複数のコマンドがある場合は配列を指定できます。CLI レジストリはコアの ACTIONS 配列からエントリーを生成するため、コマンドを別途登録する必要はありません。

プラグインインターフェース バージョン 2 では、各プラグインハンドラーと並べて PluginAction をエクスポートします。既存のパラメータメタデータは MCP 互換の inputSchema に変換され、name、description、params はプラグインの検出に引き続き使用できます。

// plugins/example/actions/list-items.js
export async function listItems({ page, params }) {
  return new MyPluginResponse(...);
}

export const listItemsAction = new PluginAction({
  name: 'list_items',
  description: 'List items from the current page',
  params: [{ name: 'limit', type: 'number', required: false, default: 10 }],
  response: MyPluginResponse,
  handler: listItems
});

アクションフォルダーの index.js は、これらの記述子を ACTIONS にインポートします。本番モジュールは個々のアクションファイルではなく、そのフォルダーのインデックスを使用します。分離が有用な場合、テストでは個々のアクションモジュールをインポートできますが、モジュールが公開するのは引き続き記述子だけです。ハンドラー、ツール、レスポンスには、そのオブジェクトを介してアクセスします。

各プラグインレベルの index.js の公開エクスポートは、マニフェスト、検出関数、アクション、情報プロバイダーを含む CorePlugin 記述子だけです。本番コードは、src/plugins/index.js がエクスポートする PLUGINS 配列を通じてのみプラグインにアクセスします。そこでエントリーを追加または削除すると、プラグインが有効または無効になります。個々のプラグインのエントリーポイントを直接インポートするのは、プラグイン固有のテストに限られます。

export const EXAMPLE_PLUGIN = new CorePlugin({
  manifest,
  matchesPage,
  actions: ACTIONS,
  getInfo,
});

プラグインハンドラーは { page, params } を受け取り、宣言されたレスポンス型、または ErrorResponse などの別の MCPResponse を返す必要があります。生のオブジェクトはアクション境界で拒否されます。

CLI モード

MCPBrowser はスタンドアロンのコマンドラインツールとしても使用できるため、シェルスクリプト、CI/CD パイプライン、またはシェルコマンドを介して動作する AI エージェント（GitHub Copilot CLI など）から簡単に利用できます。

# Show help
mcpbrowser --help

# Fetch a page (handles auth, SSO, SPAs automatically)
mcpbrowser fetch https://eng.ms/docs/my-page

# Fetch with raw HTML output
mcpbrowser fetch https://github.com --browser chrome --raw

# Take a screenshot
mcpbrowser screenshot https://example.com --output page.png --full-page

# Click an element on a loaded page
mcpbrowser click https://example.com --selector "#login-btn"

# Type into a form field
mcpbrowser type https://example.com --selector "input[name=q]" --text "search query"

# Execute JavaScript
mcpbrowser exec https://example.com --script "document.title"

# Get current HTML of a loaded page
mcpbrowser html https://example.com

CLI モードと MCP モードの違い： 引数なしで実行すると、MCPBrowser は MCP サーバーとして起動します（stdin/stdout JSON-RPC）。サブコマンドを指定して実行すると、コマンドを実行して終了します。MCP プロトコルは必要ありません。

設定（任意）

高度なセットアップ用の環境変数：

変数	説明	デフォルト
CHROME_PATH	Chrome／Edge／Brave のパス	自動検出
CHROME_USER_DATA_DIR	ブラウザープロファイルのディレクトリ	%LOCALAPPDATA%/ChromeAuthProfile
CHROME_REMOTE_DEBUG_PORT	DevTools のポート	9222

可観測性とログ記録

MCPBrowser は、状況を把握できるようすべての操作をログに記録します：

[MCPBrowser] browser_fetch_webpage called: url=https://example.com
[MCPBrowser] Tab created: example.com
[MCPBrowser] Navigating to: https://example.com
[MCPBrowser] Navigation complete: https://example.com (1234ms)
[MCPBrowser] SPA detected: React, minimal content (0 chars)
[MCPBrowser] SPA content ready
[MCPBrowser] browser_fetch_webpage completed: https://example.com

エラーメッセージには ❌ が付いています：

[MCPBrowser] ❌ browser_fetch_webpage failed: net::ERR_NAME_NOT_RESOLVED
[MCPBrowser] ❌ No open page found for example.com

ログは stderr に出力されるため、stdout 上の MCP プロトコルを妨げません。

トラブルシューティング

ブラウザーが開かない場合

• Chrome、Edge、または Brave がインストールされていることを確認してください
• CHROME_PATH を明示的に設定してみてください

ブラウザーに接続できない場合

• Chrome のすべてのインスタンスを閉じて、もう一度試してください
• ポート 9222 が使用中でないか確認してください

認証情報が保持されない場合

• ブラウザーのタブを開いたままにしてください（デフォルトの動作です）
• 関連するリクエストには同じドメインを使用してください

npx／プライベート npm レジストリで E401 エラーが発生する場合

プロジェクトにプライベートレジストリ（例：Azure Artifacts、GitHub Packages、Artifactory）を指定する .npmrc がある場合、npx は npmjs.org ではなくそのレジストリから mcpbrowser を取得しようとするため、E401 で失敗します。

修正方法： MCP 設定の env ブロックに npm_config_registry を追加します：

{
  "mcpServers": {
    "mcpbrowser": {
      "command": "npx",
      "args": ["-y", "mcpbrowser@latest"],
      "env": {
        "npm_config_registry": "https://registry.npmjs.org"
      }
    }
  }
}

別の方法： グローバルにインストールして、npx を完全に省略します：

npm install -g mcpbrowser

その後、MCP 設定では args を指定せず、"command": "mcpbrowser" を使用します。

リンク

• GitHub
• npm
• Open VSX Registry
• VS Code Marketplace
• Issues

ライセンス

MIT