browser-agent

Runbook AI MCP サーバー

Chrome 拡張機能を通じてブラウザー自動化機能を提供する MCP（Model Context Protocol）サーバーです。Claude Code のようなターミナルベースのエージェントが、現在のブラウザーセッションを使ってあらゆる Web サイトを操作できるようにします。

Runbook AI エコシステムの一部です。Discord コミュニティに参加して、フィードバックを寄せたり、開発に参加したりできます！

https://github.com/user-attachments/assets/a43fba64-bc40-4ef6-9840-e100203e2cf5

Runbook AI を選ぶ理由

ほとんどのブラウザーベースの MCP ツール（chrome-devtools-mcp など）は、ブラウザーで操作するたびに DOM 全体を送信するため、LLM のコンテキストウィンドウをすぐに使い切ってしまいます。

Runbook AI は異なります：

• コンテキストの最適化： HTML を大幅に簡略化した形式に変換します。不要な部分を取り除きながら、重要なテキストや操作要素は保持します。コンパクトで高速なため、トークンを消費しません。
• 究極の汎用性： 専用の MCP サーバーがないサイト（Expedia、LinkedIn、社内ツールなど）にも、最適な方法で対応します。
• プライバシーを最優先： すべてブラウザー内で動作します。選択した LLM プロバイダー以外へのリモート呼び出しはありません。eval() や不審なスクリプトも使用しません（Chrome 拡張機能のサンドボックスによって制限されています）。
• 効率的なナビゲーション： 簡略化された HTML はビューポートの範囲を超えて扱えるため、スクロールや複数ページにわたるタスクをより効率的に実行できます。

インストール

MCP サーバー

MCP 設定に追加します：

{
  "mcpServers": {
    "runbook-ai": {
      "command": "npx",
      "args": ["-y", "runbook-ai-mcp@latest"]
    }
  }
}

Chrome 拡張機能

Chrome ウェブストアから Runbook AI 拡張機能をインストールします。

拡張機能のサイドパネルから設定を開き、拡張機能の設定で MCP を有効にします。

LLM API キー、モデル名、ベース URL を設定します。Gemini 3 Flash（gemini-3-flash-preview）の使用を推奨します。Google AI Studio から無料の API キーを取得できます。

MCP トークン（推奨）

トークンを設定しない場合、localhost:9003 への WebSocket 接続を開けるプログラムであれば、どれでもブラウザーを操作できます。アクセスを制限するには、拡張機能の設定を開き、MCP token の横にある Generate をクリックして保存します。以降、拡張機能は同じトークンを含むリクエストのみを実行します。

--token を使って、MCP サーバーにトークンを渡します：

{
  "mcpServers": {
    "runbook-ai": {
      "command": "npx",
      "args": ["-y", "runbook-ai-mcp@latest", "--token", "<your token>"]
    }
  }
}

または、Claude Code の場合（設定の Copy setup command をクリックすると、この行がコピーされます）：

claude mcp add runbook-ai -- npx -y runbook-ai-mcp@latest --token <your token>

--token が指定されていない場合、サーバーは RUNBOOK_AI_MCP_TOKEN も読み込みます。コマンドライン引数は ps で他のユーザーから見えるため、共有マシンではこちらの使用を推奨します。トークンがない、または誤っているリクエストには、Error: invalid-mcp-token: ... が返されます。拡張機能の設定でトークンを空にすると、このチェックは無効になります。

デフォルトでは、拡張機能はすべての Web サイトにアクセスできます。アクセスを制限するには、Chrome 拡張機能の詳細を開き、サイトへのアクセス設定に個々のサイトを追加してください。

使用方法

Chrome を開き、拡張機能のサイドパネルを開いたままにします。

MCP サーバーを起動します（MCP クライアントから呼び出すと自動的に起動します）。

ツールスキーマ

サーバーが公開するツールは 1 つです：

browser-agent

AI と自動化機能を使って、Chrome ブラウザーでタスクを実行します。

パラメーター：

• prompt（文字列、必須）：AI エージェントが実行するタスクのプロンプト
• maxIterations（数値、任意）：タスクにおけるエージェントの最大反復回数（デフォルト：15）。各反復はエージェントのアクション（移動、クリック、入力など）1 回です。複数ページにわたる長いタスクでは、この値を大きくしてください。トークンの予算もこの値に応じて増加します。
• ephemeral（ブール値、任意、デフォルトは true）：各呼び出しは分離されたブラウザーセッションで実行されます。新しい空白のタブで開始し、以前の呼び出しで開いたタブは表示されず、完了時に開いたすべてのタブが閉じられます。前回の呼び出しのタブから続けて作業し、最後のページを開いたままにするには、false を指定します（同じページを使って複数回の呼び出しで進めるワークフローなど）。
• effort（文字列、任意、デフォルトは normal）：エージェントがどの程度調査を行うかを指定します。quick（読み込み済みのコンテンツをすばやく一度確認し、見つからない任意の詳細は「指定なし」として報告します。反復回数の上限も低くなります）、normal（依頼内容に応じた調査を行います）、thorough（すべてのページネーションをたどり、詳細ページを開き、候補を 1 件ずつ確認します。反復回数の上限も高くなります）のいずれかを指定します。どのレベルでも正確性のルールが適用されます。
• outputDir（文字列、任意）：エージェントが生成したファイルを書き込む、MCP サーバーを実行しているマシン上のディレクトリです（存在しない場合は作成され、同名のファイルは上書きされます）。デフォルトでは、$RUNBOOK_AI_FILES_DIR が設定されていればその下に、設定されていなければ OS の一時ディレクトリに、呼び出しごとの新しいディレクトリ runbook-ai-mcp/task-<timestamp>-<id> が作成されます。

ファイル： 実行中にエージェントが保存したもの（スクレイピングしたリストや saveToFile で取得した API ペイロードなどのファイルに書き込んだデータ、ダウンロード、抽出したデータセット、スクリーンショットなど）はディスクに書き込まれ、結果テキストの末尾に絶対パス、MIME タイプ、サイズとともに一覧表示されます。ファイルの内容が結果に直接埋め込まれることはないため、大量のデータでコンテキストが圧迫されることはありません。ファイルはご自身のツールで読み取ってください。画像ファイル（4 MB 以下）は MCP のインライン画像コンテンツとしても返されるため、スクリーンショットを直接確認できます。

大量のデータをファイルとして取得するには、プロンプトでその旨を指定します。例："... collect all orders from the account page and save them to orders.json"。

例：

{
  "name": "browser-agent",
  "arguments": {
    "prompt": "Go to google.com and search for 'MCP protocol'"
  }
}

開発

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

アーキテクチャ

1. MCP サーバー：stdio 経由で MCP クライアントと通信します
2. WebSocket サーバー：ポート 9003 で Chrome 拡張機能からの接続を待ち受けます
3. Chrome 拡張機能：ブラウザー自動化タスクを実行します

ツールが呼び出されると、次の処理が行われます。

1. MCP クライアントが stdio 経由で MCP サーバーにリクエストを送信します
2. MCP サーバーが WebSocket 経由で Chrome 拡張機能にリクエストを転送します
3. 拡張機能がタスクを実行し、結果を返します
4. 結果が MCP クライアントに返されます。エージェントが生成したファイルはディスクに書き込まれ（outputDir）、そのパスが結果に追加されます

コントリビューション

コントリビューションを歓迎します！お気軽に PR を送ってください。