usable-browser-agent

Usable Browser Agent（無料の個人利用／評価向けプラン）

MCP サーバーとブラウザー拡張機能の組み合わせにより、AI エージェント（Claude Code、Codex、または任意の MCP クライアント）が使い捨ての自動操作ブラウザーではなく、ログイン済みのセッションを含む実際のブラウザーを操作できます。最初に一度だけ手動でログインすれば、エージェントはあなたとして操作します。

このリポジトリは無料プランです。商用版と同じ、単一セッションの MCP サーバーで、個人の非商用利用と、購入前の製品評価を対象とするライセンスが付属します。このプランの Firefox 拡張機能は Firefox Add-ons で公開されています。商用利用（ビジネスにおける利用、有償のクライアント業務での利用、商用製品またはサービスへの組み込み）には商用ライセンスが必要です。商用ライセンスは https://savvytechsphere.com/usable-browser-agent で一度限りの $39 で購入でき、Chrome 版も含まれます。理由を問わない14日間の返金保証が付いています。どちらのプランにもライセンスキーはなく、ライセンスキーの有無を確認することもありません。両プランの違いは、ライセンスの許諾範囲と拡張機能の識別情報だけです。

パスワードがエージェントに渡ることはありません。 エージェントがログインする際に渡すのは秘密の エイリアス だけで、パスワードの値は渡しません。認証情報はローカルの保管庫に保存され、ドメインが制限されるため、別のサイトでは使用が拒否されます。また、エージェントが読み取る内容やスクリーンショットから認証情報は除外されます。詳しくは docs/CREDENTIAL-SAFETY.md をご覧ください。

仕組み

Claude Code / Codex / any MCP client
      |  MCP over stdio
      v
  MCP server (Node, this repo)  --hosts-->  WebSocket  ws://127.0.0.1:8876
      ^                                          ^
      | 53 browser_* tools                       | (extension connects out)
      +------------------------------------------+
                                       Firefox extension (from Firefox Add-ons)
                                       your real profile, your logins -> DOM actions on the active tab

エージェントは、すべての対話可能な要素に安定した [ref=eN] ハンドルが付いたアクセシビリティ／DOM スナップショットを使ってページを認識し、ref を指定してクリックや文字入力を行います。座標を推測したり、ビジョンモデルを使ったりする必要はありません。すべての処理はお使いのマシン上で実行されます。MCP は stdio 経由で動作し、拡張機能は 127.0.0.1 にバインドされた WebSocket 経由でサーバーと通信します。データがコンピューターの外に出ることはありません。

エージェントは、常に現在アクティブなタブを操作します。操作させたいタブにフォーカスを当ててください。

はじめに（約2分）

必要なのは2つです。エージェントが起動するこの MCP サーバー と、Firefox Add-ons から一度だけインストールする Firefox 拡張機能 です。

1. サーバーを入手してインストーラーを実行する

Node.js 18 以降と Firefox 142 以降が必要です（まずは macOS 向けです。docs/INSTALL.md をご覧ください）。

npm install -g usable-browser-agent
uba-install

または、このリポジトリをチェックアウトしたディレクトリから実行します。

git clone https://github.com/Savvy-Tech-Sphere/usable-browser-agent-free.git
cd usable-browser-agent-free
node bin/uba-install.mjs        # or: npm run setup

（ダウンロードする場合は、Releases ページから zip をダウンロードして解凍し、フォルダー内で同じコマンドを実行してください。）

インストーラーは Node とポートを確認し、依存関係をインストールします。また、このコピーの絶対パスを使って Claude Code および／または Codex に MCP サーバーを登録し、スモークテストを実行します。さらに、初回ログイン情報を任意で保存し、macOS の権限設定手順を表示します。インストーラーは何度実行しても既存の設定を上書きしません。--non-interactive を指定すると、すべてのデフォルト設定が選択されます。

2. Firefox 拡張機能をインストールする（初回のみ）

Firefox Add-ons から Usable Browser Agent (free) をインストールします。 https://addons.mozilla.org/firefox/addon/usable-browser-agent-free/

拡張機能がエージェントの起動した MCP サーバーに接続するまでは、ツールバーのバッジに off と表示されます。接続すると ON に変わります。（インストーラーには、商用版に該当する .xpi と Chrome の手順も表示されます。無料プランでは Add-ons の掲載ページからインストールするだけで十分です。）

3. ログインして使い始める

エージェントに使わせたいサイトにログインしてから、ブラウザータスクを依頼します。たとえば、「アクティブなタブで通知を開いて、自分の対応待ちのプルリクエストを一覧表示して」と依頼します。エージェントはページのスナップショットを取得し、ref を指定して操作します。

インストーラーを使わずに手動で設定する場合：

# Claude Code (user scope, works from anywhere afterward):
claude mcp add browser --scope user -e UBA_PORT=8876 -- node "$PWD/server/index.js"

# Codex: add to ~/.codex/config.toml (use the absolute path to your copy):
[mcp_servers.browser]
command = "node"
args = ["/ABSOLUTE/PATH/TO/usable-browser-agent-free/server/index.js"]

[mcp_servers.browser.env]
UBA_PORT = "8876"

ヘルプ：docs/INSTALL.md、docs/TROUBLESHOOTING.md、docs/UNINSTALL.md。

強化モードがデフォルトです

browser_eval（ページ内で任意の JavaScript を実行する機能）は、明示的に有効にしない限りオフです。また、パスワードフィールドの近くではスクリーンショットがブロックされます。CAPTCHA、ボット対策の壁、二要素認証のプロンプトは意図的に自動化しません。ご自身の画面上のブラウザーを操作するため、エージェントは必要に応じてご自身に対応を求めます。同時に操作できるタブは1つです。

使い方

1. Firefox または Chrome を開き、エージェントに使わせたいサイトにログインします。
2. 拡張機能のバッジがオンになっていることを確認します。
3. Claude Code / Codex に操作を依頼します。たとえば、*「アクティブなタブで X を検索し、最初の検索結果をカートに追加してください」*と指示します。エージェントはページのスナップショットを取得してから、ref を指定して操作します。

ワークフローの記憶

Usable Browser Agent は、エージェントが変化する同じウェブサイトの操作手順を毎回一から調べ直さずに済むよう、ローカルのワークフロー記憶を保持します。たとえば「Google Play Console で新しいアプリを作成する方法」のような、再利用可能なタスク知識を保存します。これには、現在のページ名、画面に表示されるボタンのラベル、注意点、成功した手順の順序などが含まれます。

デフォルトのファイル：

~/.local/state/usable-browser-agent/workflow-memory.jsonl

UBA_MEMORY_FILE=/path/to/workflow-memory.jsonl で保存先を変更できます。このファイルは追記専用の JSONL で、モード 0600 で作成されます。通常の呼び出しでは、後から置き換えられた記録や、忘れるよう指定された記録は参照されません。この記憶は、設定したマシンとファイルパス内にのみ保存されます。複数のエージェントが同じ管理下のファイルを参照するように設定しない限り、同期されません。

エージェントの想定されるループ：

1. サイトで同じタスクを繰り返す場合や複数のステップを伴うタスクを行う前に、タスクやサイトを指定して browser_workflow_recall を呼び出します。
2. 一致する記憶があれば出発点として利用し、browser_snapshot で現在のページを確認します。
3. 新しい手順や変更された手順で操作に成功したら、再利用できる手順を指定して browser_workflow_remember を呼び出します。
4. 古い記憶が誤っている場合は、supersedes: ["old_id"] を指定して置き換えを保存するか、参照対象から削除するには browser_workflow_forget を呼び出します。

アクティブなタブのドメインに保存済みの記憶がある場合、browser_status、browser_info、browser_navigate、browser_snapshot もワークフロー記憶の短いヒントを返します。ヒントは意図的に簡潔にしています。手順全体を確認するには browser_workflow_recall を呼び出してください。

パスワード、ワンタイムコード、ワークフローに不要なアカウント識別子の生データ、一時的な [ref=eN] ハンドルは保存しないでください。記憶ストアは、一時的な ref を含む手順の保存を拒否し、クエリー文字列を削除して、アカウント／アプリ／デベロッパー ID と思われるパスのセグメントを置き換えることで、保存する URL をサニタイズします。スナップショットのたびに ref は再構築されるため、代わりに画面上のラベルやページ／セクション名を保存してください。

認証情報ブローカー

browser_login と browser_fill_secret を使うと、エージェントは認証情報の値を受け取ることなくログインを実行できます。MCP クライアントが渡すのは、シークレットのエイリアスと要素の参照のみです。平文が流れるのは次の経路だけです。

secrets file -> MCP server -> local WebSocket -> browser extension -> DOM field

デフォルトの保管庫ファイルは ~/.config/usable-browser-agent/secrets.json です。UBA_SECRETS_FILE=/path/to/secrets.json で変更できます。サーバーは必要に応じて親ディレクトリを作成し、シークレットファイルがグループやその他のユーザーから読み取り可能な場合は警告します。アクセス権は 0600 にしてください。

ファイルは JSON 配列です。

[
  {
    "alias": "github",
    "domains": ["github.com"],
    "username": "[email protected]",
    "password": "replace-with-real-secret"
  }
]

domains は許可するホスト名です。完全一致とサブドメインの一致が許可されるため、github.com は gist.github.com に一致しますが、evilgithub.com には一致しません。

ログインには、スナップショットを取得した後、入力と送信をまとめて行うツールを使うことをおすすめします。

browser_login({
  "secret": "github",
  "username_ref": "e12",
  "password_ref": "e13",
  "submit_ref": "e14"
})

browser_login は、username_ref が指定され、シークレットにユーザー名が設定されている場合はユーザー名を入力し、パスワードを入力した後、拡張機能の 1 回のアクションで送信します。submit_ref が省略された場合は、パスワードフィールドを含むフォームを送信し、フォールバックとして Enter キーを押します。ツールが返すのは、logged in via [e14] や submitted form のようなステータス文字列のみです。

ログイン以外のフローでは、引き続き browser_fill_secret を利用できます。

browser_fill_secret({ "ref": "e12", "secret": "github", "field": "username" })
browser_fill_secret({ "ref": "e13", "secret": "github", "field": "password" })

意図的に value 引数はありません。アクティブなタブのホストがエイリアスで許可されていない場合、サーバーは入力を拒否し、値をブラウザーに送信しません。

読み取りとスクリーンショットは、多層的に保護されています。

• パスワードフィールドと認証情報ブローカーによって入力されたフィールドは、スナップショットと browser_get_value でマスキングされます。
• browser_screenshot は、ブローカーによる入力またはログインが進行中の場合、入力済みのパスワードフィールドがある場合、またはいずれかのフィールドがシークレット入力済みとしてマークされている場合にブロックされます。ログイン後の画面遷移で認証情報フィールドがなくなると、再びスクリーンショットを撮影できます。
• サーバーはマスキングのために保管庫を遅延読み込みし、browser_read_text や browser_eval の結果を含む、すべての送信ツール結果から設定済みのシークレット値を除去します。

強化モードはデフォルトで有効です。任意の JavaScript を実行するための browser_eval のエスケープハッチは無効になり、パスワードフィールドが空でも存在する場合はスクリーンショットがブロックされます。browser_eval のエスケープハッチを利用する必要がある場合は、サーバーの環境で UBA_STRICT_SECRETS=0 を設定してオプトアウトしてください。Claude Code では、browser はすでに登録されており、claude mcp add は既存の名前を拒否するため、インストール時のポートである UBA_PORT を維持したまま、削除して再登録してください（インストールフォルダーから実行します）。

claude mcp remove browser --scope user && \
claude mcp add browser --scope user -e UBA_PORT=8876 -e UBA_STRICT_SECRETS=0 -- node "$PWD/server/index.js"

UBA_SECRETS_FILE を設定してインストールした場合は、そのコマンドにも -e UBA_SECRETS_FILE=<absolute path> を追加してください。追加しないとサーバーはデフォルトの保管庫を使い、保存したログイン情報を解決できなくなります。インストーラーを再実行すると、利用環境に応じた正確なコマンドが表示されます。

Codex では、[mcp_servers.browser.env] の下に UBA_STRICT_SECRETS = "0" を追加してください。サーバー設定を反映するには、エージェントを再起動します。

スクリーンショットのブロックは、時間と状態に基づくガードです。返される画像内で認証情報フィールドをマスクする機能は v2 の候補であり、現時点では実装されていません。

ツール（53）

ツール	用途
browser_workflow_recall	繰り返し行うタスクやサイトが変化するタスクを始める前に、ローカルのワークフローメモリを検索します
browser_workflow_remember	検証済みで再利用可能なワークフローの手順、注意点、長期的に有効な UI の手がかりを保存します
browser_workflow_forget	古くなった機密情報や誤ったワークフローメモリを無効化します
browser_snapshot	[ref=eN] ハンドル付きのアクセシビリティ／DOM ツリー — 主な認識ツールです
browser_navigate / browser_back / browser_forward / browser_reload	ナビゲーション
browser_click	ref でクリックします — 右／中ボタン、ダブルクリック、ctrl／shift／alt／meta 修飾キーに対応します
browser_drag	ある要素を別の要素にドラッグします（カンバン、並べ替え可能なリスト、スライダー）
browser_type	ref でフィールドに入力します（submit = Enter キーを押す、は任意です）
browser_fill_form	1 回の呼び出しで複数のフィールド [{ref,text}] に入力します
browser_fill_secret	サーバー側のシークレットエイリアスを使ってユーザー名／パスワードを入力します
browser_login	サーバー側のシークレットエイリアスからユーザー名／パスワードを一括入力して送信します
browser_select	ラベル／値で <select> のオプションを選択します
browser_hover / browser_press_key / browser_scroll	ポインターとキーボード操作（ウィンドウまたは特定のコンテナーをスクロールします。無限スクロールでは to:'bottom' を指定します）
browser_upload_file	ファイル入力欄またはドロップゾーンにローカルファイルを添付します — OS のファイル選択ダイアログは使用しません
browser_paste	テキストまたはクリップボードから、要素に実際の貼り付けイベントを送ります（リッチエディター）
browser_clipboard_read / browser_clipboard_write	クリップボードのテキストを読み取り／書き込みます
browser_clipboard_read_image / browser_clipboard_write_image	クリップボードの画像を読み取り／書き込みます
browser_set_dialog_policy / browser_dialogs	alert／confirm／prompt に自動応答します（処理をブロックしません）。ページが何を尋ねたかを確認できます
browser_mock_geolocation	navigator.geolocation が固定位置を返すようにします（権限の確認を省略します）
browser_download / browser_downloads_list	URL をディスクにダウンロードし（保存ダイアログなし）、ローカルパスを取得します
browser_save_pdf	現在のタブをダウンロードフォルダーに PDF として保存します
browser_network_log	最近のネットワークリクエスト（メソッド、URL、ステータス、エラー）を調べます
browser_http_auth / browser_clear_http_auth	シークレットエイリアスを使って、ネイティブの HTTP 基本認証プロンプトに応答します
browser_read_text / browser_get_value	ページ／要素のコンテンツを読み取ります
browser_wait / browser_wait_for_text	待機
browser_list_tabs / browser_select_tab / browser_new_tab / browser_close_tab	タブ
browser_status / browser_info / browser_screenshot	診断とビジョンによるフォールバック
browser_native_status	OS レベルの入力の可用性と必要なセットアップを報告します
browser_os_type / browser_os_key	実際の OS 信頼済みキー入力を行います（isTrusted を確認するページ向け）。macOS
browser_os_click / browser_os_click_ref	実際の OS 信頼済みマウスクリックを行います（画面座標または要素 ref）。macOS + cliclick
browser_native_dialog	ネイティブブラウザーのダイアログを調べ、操作します（ファイル選択、印刷、基本認証、「ページを離れますか？」）。macOS
browser_focus_browser	OS レベルの入力を行うため、Firefox を前面に表示します。macOS
browser_request_human_help	CAPTCHA／ボット対策画面／2FA の対応を人間に引き継ぎます
browser_eval	ページのサンドボックスで JS を実行します。強化モード（デフォルト）では無効です。UBA_STRICT_SECRETS=0 で有効にできます

カバレッジの段階

ツールセットは、人間が実行できるあらゆるブラウザータスクをエージェントが完了できるように設計されています。

1. ページ内の操作（クリック、右クリック／ダブルクリック／修飾キー付きクリック、ドラッグ＆ドロップ、入力、ダイアログ、コンテナーのスクロール、クリップボード）—すべてページ内で処理します。
2. ブラウザーレベルの機能（保存ダイアログを表示しないダウンロード、PDF として保存、HTTP 基本認証、ネットワークの検査、位置情報）—WebExtension API を介して処理します。
3. 最後の仕上げ—ネイティブのブラウザー UI（ファイル選択ダイアログ、印刷／認証ダイアログ）や、OS に信頼された入力（event.isTrusted）を要求するページです。MCP サーバーは Mac 上で動作するため、browser_os_* と browser_native_dialog で実際のキーボード／マウス操作やネイティブダイアログを制御できます。OS レベルの入力を参照してください。
4. 人間への引き継ぎ—CAPTCHA やボット対策の壁は意図的に自動化していません。実際のブラウザーが画面上に表示されているため、browser_request_human_help で通知し、対応をお願いします。

注意事項と制限

• クロスオリジンの iframe は、Firefox がフレームへの拡張機能コンテンツスクリプトの挿入を許可している場合にサポートされます。子フレームの ref には内部的にプレフィックスが付加され、そのフレームに処理が戻されます。スナップショットとアクションでは、オープン Shadow DOM もサポートされています。
• 特権ページ（about:、addons.mozilla.org、PDF ビューアー、view-source）では、設計上 Firefox が拡張機能をブロックするため、拡張機能でスクリプトを実行できません。必要に応じて、OS レベルのサイドカー（以下を参照）で引き続き入力やクリックを行えます。
• ネイティブ OS ダイアログ（ファイル選択、印刷、基本認証のプロンプト）は、次の 3 つの方法で処理します。ファイル選択ダイアログは開く必要がありません（browser_upload_file が入力を直接設定し、browser_click はファイル入力を拒否します）。基本認証には browser_http_auth で応答します。それ以外は macOS 上で browser_native_dialog を使って操作できます。
• CAPTCHA／ボット対策の壁は意図的に自動化していません。実際のブラウザーが画面上に表示されているため、browser_request_human_help でご自身に引き継いでください。
• ポートは 8876（UBA_PORT）です。公開されている拡張機能はこのポートに接続するため、無料プランではデフォルトのままにしてください。
• 一度に接続できるブラウザー／拡張機能は 1 つだけです。最も新しい拡張機能の hello が優先されます（再読み込みにも対応します）。ポート上のソケットは、拡張機能であることを識別するまで無視されます。
• UBA_BROWSER_APP_NAME（macOS、任意）：信頼されたクリックの前に OS レベルの入力ツールがフォーカスするアプリケーションを上書きします。デフォルトでは、接続中の拡張機能ビルドに応じて Firefox または Google Chrome が選択されます。標準外のインストール（Chromium、Chrome for Testing）では値を設定してください。明示的に指定したアプリケーションにフォーカスできない場合、OS レベルのクリックは、手前に表示されている別のアプリケーションをクリックするのではなく、エラーを明確に返します。
• MCP サーバーが Cookie やネットワークに直接触れることはありません。拡張機能に構造化コマンドを中継するだけで、実際の処理はブラウザー内の拡張機能が行います。

OS レベルの入力（macOS）

最後の仕上げとして、ネイティブのブラウザー UI や、event.isTrusted を確認して合成入力を拒否するページを操作する場合、MCP サーバーは実際のキーボードとマウスを制御できます。MCP サーバーは拡張機能のサンドボックス内ではなく、Mac 上で動作するためです。これらのツールは browser_os_type、browser_os_key、browser_os_click、browser_os_click_ref、browser_native_dialog、browser_focus_browser です。

ページ内ツール（browser_click、browser_type など）を優先してください。そちらのほうが高速で信頼性も高いためです。OS レベルのツールは、ページ内ツールが実際に機能しない場合にのみ使用してください。

初回のセットアップ：

1. アクセシビリティ権限（信頼されたキー入力とネイティブダイアログの制御に必要）： システム設定 → プライバシーとセキュリティ → アクセシビリティを開き、MCP サーバーを実行しているアプリケーション（ターミナル、iTerm、IDE）を有効にします。この権限がないと、System Events のキー入力は何も行われずに終了します。
2. cliclick（生の座標クリックにのみ必要—browser_os_click*）：

   brew install cliclick
   

browser_native_status（または npm run native）を実行すると、利用可能な機能を確認できます。信頼されたキー入力とネイティブダイアログの制御はアクセシビリティ権限だけで動作します。生のクリックには cliclick も必要です。

動作確認

npm run smoke    # MCP server boots, lists tools, bridge listens (no Firefox needed)
npm test         # credential-safety claims + workflow-memory unit tests (no Firefox needed)

セキュリティ

このツールを使うと、AI エージェントが、ログイン中のサイトであなたに代わって実際の操作を行えます。**この用途での使用を承認した、リスクの低いサイトにのみログインしてください。**アクティブなタブは操作可能な状態にあると考えてください。エージェントがそのタブでできることは、何でも実行する可能性があります。使用中は、機密情報を扱うサイトからログアウトするか、そのようなサイトを開かないでください。

認証情報をエージェントから保護する方法（エイリアスのみのログイン、ドメインロック、マスキング、強化モード）と、それでも保護されないものについては、 docs/CREDENTIAL-SAFETY.mdをご覧ください。

ライセンスと法的事項

Usable Browser Agentは、Savvy Tech Sphere, LLCのプロプライエタリソフトウェアです。この無料プランはLICENSE.txtに準拠します（個人利用、非商用利用、および評価目的）。商用ライセンスはhttps://savvytechsphere.com/usable-browser-agentで39ドルの買い切り価格で販売されています（販売者：Lemon Squeezy）。現状有姿での提供となり、購入者自身で利用できるセルフサービス形式で、14日間の返金期間があります。個別サポートはありません。各プランに含まれる内容の詳細はdocs/FREE-TIER.mdをご覧ください。

• legal/ACCEPTABLE-USE.md：自分自身のアカウントのみを自動化し、各サイトの利用規約に従ってください
• legal/PRIVACY.md：ソフトウェアは何も収集せず、すべての処理をお使いのマシン上で実行します

お問い合わせは、https://savvytechsphere.com/#contactのお問い合わせフォームからお願いします。