MCP エージェント連携

Sa2web MCP Server は、リモートブラウザーを標準 MCP ツールとして Claude Code、Claude Desktop、Cursor、Windsurf、VS Code Copilot、Cline、Roo Code、opencode、Gemini CLI、Zed、Hermes Agent、OpenClaw などに提供します。

MCP プロジェクトは sa2web/sa2web-mcp で公開され、npm では @sa2web/mcp として配布されています。

ターミナルから直接操作する場合は、リモートブラウザー CLI を参照してください。

対象サイトは iframe#rbi-frame 内に表示され、Server が Playwright 経由で操作します。

インストール

Node.js 18 以降を用意し、npm パッケージをグローバルインストールします。

npm install @sa2web/mcp -g
npx playwright install --with-deps

これで sa2、sa2-browser、MCP Server 入口の sa2-mcp が利用できます。

ソース開発時は公開リポジトリを clone してビルドします。

git clone https://github.com/sa2web/sa2web-mcp.git
cd sa2web-mcp
npm install
npx playwright install --with-deps
npm run build

クライアント設定

グローバルインストール後は sa2-mcp を直接指定します。

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "sa2-mcp",
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

グローバルコマンドを解決できないクライアントでは、sa2-mcp のフルパス、またはソースビルドの /absolute/path/to/sa2web-mcp/dist/server.js を node で指定してください。

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "node",
      "args": ["/absolute/path/to/sa2web-mcp/dist/server.js"],
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

VS Code Copilot のルートフィールドは servers、opencode は mcp、Zed は context_servers です。Hermes Agent は ~/.hermes/config.yaml の mcp_servers、OpenClaw は Gateway の mcp.servers に追加します。保存後にクライアントを再起動し、sa2_help が表示されることを確認します。

認証情報

実際の clientSecret を Git やドキュメントに保存しないでください。漏えいした認証情報は直ちに更新してください。

主な環境変数

変数	デフォルト	用途
SA2_LOGIN_URL	なし	必須のエージェントログイン URL。リモートブラウザー origin もここから推定
SA2_AUTO_LOGIN_BEFORE_NAVIGATE	true	対象を開く前に自動ログイン
SA2_HEADLESS	false	Playwright のヘッドレス実行
SA2_BROWSER	chromium	chromium、firefox、webkit
SA2_IGNORE_HTTPS_ERRORS	true	HTTPS 証明書エラーを無視するかどうか。false にすると有効な証明書を要求
SA2_RBI_FRAME_CONTENT_WAIT_MS	15000	対象 iframe の待機時間
SA2_NAVIGATION_TIMEOUT_MS	45000	ナビゲーションのタイムアウト
SA2_ACTION_TIMEOUT_MS	15000	操作のタイムアウト
SA2_LOG_LEVEL	info	ログレベル
SA2_LOG_STDERR	true	stdout を MCP 用に保ち、ログを stderr に出力
SA2_LOG_FILE	なし	任意のログファイル

旧変数 SA2_REMOTE_BROWSER_PREFIX と SA2_REMOTE_BROWSER_BASE_URL は不要です。

推奨フロー

sa2_help
  -> sa2_list_available_targets    # SaaS、ワークスペース、内部サイトのみ
  -> sa2_open_target
  -> browser_snapshot / browser_extract_text
  -> browser_click / browser_type / browser_press / browser_wait

公開 URL:

{ "type": "cloud", "url": "https://example.com" }

保存済み対象は sa2_list_available_targets の ID を使用します。

{ "targetId": "workspace:123" }

ページを開いた後は browser_snapshot を優先し、返された ref=eN をクリックや入力に渡します。id=tN と context=[tN] はスナップショット内のテキスト参照であり、CSS selector や操作可能な ref ではありません。

全ツールリファレンス

現在の Server に登録されている全ツールを示します。引数は MCP の arguments オブジェクトです。

ツール	用途、主な引数、戻り値
sa2_help	引数なし。推奨フロー、例、互換ツール一覧を返します。
sa2_list_available_targets	引数なし。プロキシ、SaaS、ワークスペース、内部サイトと安定した targetId を返します。
sa2_open_target	推奨ナビゲーション。公開 URL は type=cloud と url、保存済み対象は targetId または type と id/name。surf、waitUntil も指定可能です。
browser_open_login	SA2_LOGIN_URL を開きます。任意の waitUntil。ログイン診断用です。
browser_navigate	互換用の公開 URL ナビゲーション。url 必須、surf と waitUntil は任意です。
browser_navigate_back	引数なし。外側ツールバーで戻ります。後で snapshot を更新します。
browser_navigate_forward	引数なし。外側ツールバーで進みます。
browser_reload	引数なし。外側ツールバーで再読み込みし、古い refs を無効にします。
browser_list_proxies	引数なし。free-browse 設定、プロキシ、direct を含む options を返します。
browser_list_saas_sites	引数なし。SaaS カテゴリとフラットなサイト一覧を返します。
browser_enter_saas_site	id または name で SaaS を開き、任意の waitUntil と一致サイトを返します。
browser_list_workspaces	引数なし。ワークスペースの生データとアカウント単位の一覧を返します。
browser_enter_workspace	accountId、または siteId + username でアカウントを開きます。
browser_list_inner_sites	引数なし。利用可能な内部サイトを返します。
browser_enter_inner_site	id または name で内部サイトを開きます。
browser_snapshot	任意の実 CSS filter。iframe ツリーの意味スナップショットを返します。操作には ref=eN を使い、id=tN は使いません。
browser_extract_text	任意の実 CSS selector。iframe ツリーの可視テキストを返します。
browser_click	ref、selector、role/name、text、または x/y でクリックします。
browser_type	text 必須。ref/selector/role で入力先を指定し、append と pressEnter を利用できます。
browser_press	key 必須。Enter、Escape、Control+A などを送信します。
browser_press_key	browser_press と同じ引数・動作の互換エイリアスです。
browser_wait	selector、text、urlIncludes、または ms（既定 1000）を待ちます。
browser_scroll	root または要素を by/to/intoView でスクロールします。引数なしでは下へ 600px。
browser_hover	ref、selector、role/name、text で要素に hover します。
browser_drag	startRef/startSelector から endRef/endSelector へドラッグします。
browser_fill_form	locator と必須 value を持つ fields 配列を順に fill します。
browser_select_option	select を ref/selector で指定し、values、value、label、index で選択します。
browser_check	ref、selector、role/name、text で checkbox または radio をオンにします。
browser_uncheck	同じ locator 形式で checkbox をオフにします。radio は対象外です。
browser_file_upload	file input を ref/selector で指定し、Server が読める path/paths をアップロードします。
browser_paste	text、html、rtf、path/paths を対象またはフォーカス要素へ貼り付けます。
browser_handle_dialog	alert/confirm/prompt を処理します。accept は既定 true、promptText と timeoutMs は任意です。
browser_resize	正の width と height が必須。通常 viewport または有効なデバイスモードの寸法を変更します。
browser_list_devices	引数なし、ページも開きません。Desktop と全 Playwright デバイスの viewport、screen、DPR、touch/mobile、ブラウザー種別を返します。
browser_toggle_device	context を作り直さずデバイスを切替。enabled、device、寸法、DPR、touch、UA、orientation、reload を受け取り、state、observed、targetObserved、warnings を返します。
browser_screenshot	PNG を返します。fullPage の既定は false。
browser_take_screenshot	互換 screenshot。fullPage の既定は true。
browser_evaluate	iframe 内で expression と任意の arg を実行して JSON を返します。
browser_run_code	Playwright の page、rootFrame、helpers で非同期 code を実行します。信頼できるコードだけを使用します。
browser_close	引数なし。browser/context と refs、ログイン、dialog、CDP、デバイス状態を消去します。

デバイス切替

まず browser_list_devices で正確なプリセット名を取得します。browser_toggle_device に { "device": "Pixel 7", "orientation": "portrait" } を渡すと、cookie とログイン状態を保ったまま切り替わります。新しい UA を後続リクエストに使う場合は reload: true にします。{ "device": "Desktop" } で元のデスクトップ viewport に戻ります。

Chromium は CDP で viewport、screen、DPR、touch、orientation、UA を動的に上書きします。Firefox/WebKit は viewport のみで、制限は warnings に返されます。外側の実測値は observed、対象 iframe の実測値は targetObserved です。切替後は snapshot を更新してください。

安全性とトラブルシューティング

公開、送信、削除、購入、承認、送金、メッセージ送信など外部に影響する操作は、実行前に必ずユーザーの明示的な確認を得てください。

• ツールが表示されない: ビルドと node / dist/server.js の絶対パスを確認し、クライアントを再起動します。
• ログインできない: SA2_LOGIN_URL、認証情報、アカウント状態を確認します。
• ツールバーしか見えない: browser_wait を呼ぶか、iframe の待機時間を増やします。
• 要素が見つからない: 最新の snapshot を取り、最新の ref=eN を使用します。