Chrome Browser MCP

プライベートなChatGPT開発者モードアプリが、デスクトップのGoogle Chromeで開いているタブを検査・制御できるようにするローカルブリッジです。

現在のパッチバージョン: 0.1.2。各パッチはこのバージョンを更新する必要があります。CIは更新されていないパッチを拒否します。

このブリッジは17個のMCPツールを公開します:

• 読み取り: browser_status, list_tabs, get_active_tab, read_tab, read_tabs, search_tabs

• 操作: click, type, fill_form, press_key, scroll, select_option, navigate, new_tab, close_tab

• ChatGPT子エージェント: spawn_chatgpt_agent, read_chatgpt_agent

spawn_chatgpt_agent はデフォルトでバックグラウンドに新しい chatgpt.com タブを開き、ユーザーが指定したプロンプトを正確に送信し、そのタブIDを返します。read_chatgpt_agent は通常のタブと同じ制限付きセマンティック抽出器を使用してその子タブを読み取ります。子がまだ生成中の場合、後でもう一度呼び出してください。

操作ターゲットは、CSSセレクターまたは正確な表示テキスト / aria-label / プレースホルダー / 名前 / 関連するラベルテキストのいずれかを受け入れます。曖昧なターゲットは推測せずに失敗します。

このブリッジは、Cookie、ローカルストレージ、セッションストレージ、保存されたパスワード、非表示の入力値、任意のJavaScript実行、Chrome内部ページ、シークレットタブを公開しません。ChromeデバッガーAPIも使用しません。

実証済みの経路

エンドツーエンドテストは、実際のChromiumプロセスをアンパックされたManifest V3拡張機能とともに起動し、実際のネイティブメッセージングホストを起動し、Streamable HTTP経由でMCPクライアントを接続し、ライブページを開いて一覧表示・読み取り、パスワード入力値が返されないことを検証します。ユニット/統合テストは、ページ操作、MCPルーティング、ChatGPT子エージェントツールの登録/構成、生成された拡張機能バージョンの同期、およびChrome/ネイティブメッセージングが使用するランタイムファイルがGitで追跡されていることを検証します。

MCP client
  -> http://127.0.0.1:2091/mcp
  -> native host process
  -> Chrome Native Messaging
  -> MV3 extension
  -> live Chrome tabs

すべてのゲートを実行:

npm ci
npm run check

Related MCP server: sansan-chrome-mcp

アーキテクチャ

ChatGPT developer-mode app
          |
          | OpenAI Secure MCP Tunnel (outbound HTTPS)
          v
127.0.0.1:2091/mcp
          |
          | same local Node process
          v
Chrome Native Messaging host
          |
          v
Chrome MV3 extension
          |
          +-- chrome.tabs
          +-- chrome.scripting (isolated-world reads + actions)

Chromeは拡張機能が接続するとネイティブホストを起動します。ネイティブホストはループバックMCPエンドポイントを起動します。したがって、ChatGPTがアプリを使用するときは常にChromeが開いていて、拡張機能が有効である必要があります。

要件

• macOS

• Google Chrome 120+

• Node.js 20+

• Developer Modeが利用可能なChatGPTアカウント

• Tunnels Read + Use権限を持つOpenAI PlatformトンネルIDとランタイムAPIキー

• tunnel-client

1. ネイティブホストをインストールし、拡張機能を一度読み込む

npm run install:mac

これにより、ネイティブホストのマニフェストが以下にインストールされます:

~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.komaksym.chrome_browser_mcp.json

次に:

1. chrome://extensions を開きます。

2. デベロッパーモードを有効にします。

3. パッケージ化されていない拡張機能を読み込むをクリックします。

4. このリポジトリの dist/extension ディレクトリを選択します。

5. 拡張機能IDが正確に以下であることを確認します:

jlpddlfiallighiohmhhkemgbhofpnha

IDが異なる場合は続行しないでください。ネイティブホストはその正確な拡張機能オリジンのみを受け入れます。

2. 将来のパッチの更新

拡張機能ディレクトリを選択するのは一度だけです。 dist/ 配下のビルド済み拡張機能とMCPブリッジはGitにコミットされており、CIはコミットされたランタイムビルドが古いソース変更を拒否します。

以降のパッチごとに、通常の更新フローは正確に次のとおりです:

git pull

次に chrome://extensions を開き、更新をクリックします。拡張機能のパスを再度選択したり、公開されたパッチを消費するためだけに別のビルドコマンドを実行したりしないでください。

git pull は dist/extension（Chromeが読み込むもの）と dist/bridge（ネイティブホストが実行するもの）の両方を更新します。更新をクリックすると、アンパックされた拡張機能/ネイティブメッセージング接続がリロードされ、新しくプルされたランタイムが使用されます。

表示される拡張機能のバージョンは、パッチごとに変更する必要があります。このパッチでは 0.1.2 と表示される必要があります。古いバージョンが表示されている場合、プルされたランタイムは適用されていません。

3. ローカルブラウザチェーンを検証する

Chromeを開いたままにして、次を実行します:

npm run verify:local

成功したチェックでは、以下が出力されます:

• 拡張機能ID;

• 拡張機能バージョン;

• MCPサーバーバージョン;

• 宣伝されている17個のMCPツール。

検証ツールは、拡張機能とMCPのバージョンが異なる場合、またはブリッジが古すぎてMCPバージョンを報告しない場合に失敗します。これにより、古い15ツールのブリッジを古いChrome拡張機能と即座に区別できます。

4. セキュアMCPトンネルを構成する

OpenAI PlatformでトンネルとランタイムAPIキーを作成します。次に:

export CONTROL_PLANE_API_KEY="sk-..."
./scripts/configure-tunnel.sh tunnel_0123456789abcdef0123456789abcdef

tunnel-client doctor --profile chrome-browser-mcp --explain
tunnel-client run --profile chrome-browser-mcp

プロファイルはトンネルを以下に転送します:

http://127.0.0.1:2091/mcp

ChatGPTがブラウザツールを必要とするときはいつでも tunnel-client run をアクティブに保ちます。

5. ChatGPTに追加する

1. ChatGPTで、設定 -> セキュリティとログイン -> デベロッパーモードを有効にします。

2. 設定 -> プラグインを開きます。

3. + をクリックしてデベロッパーモードアプリを作成します。

4. 接続タイプとしてトンネルを選択します。

5. トンネルIDを選択または貼り付けます。

6. app-metadata.json のメタデータを使用します。

7. ChatGPTが17個すべてのツールを検出することを確認します。

8. 新しいチャットで、+ -> その他をクリックし、Chrome Browserを選択して、開いているChromeタブを一覧表示して。 と尋ねます。

正確な検証とトラブルシューティングについては、docs/CHATGPT_SETUP.md を参照してください。

セキュリティモデル

Webページのテキストはデータであり、権限ではありません。すべてのコンテンツ結果には明示的な信頼できないコンテンツマーカーが含まれ、ツールの指示はモデルにページ内の指示をアクションに変えないように指示します。

拡張機能は、通常の開いているタブを読み取り、操作できるように、すべてのHTTPおよびHTTPSページへのアクセスを意図的に要求します。保護境界は次のとおりです:

• 拡張機能はあなたがローカルに読み込みます;

• Chromeは許可リストに登録された正確なネイティブホストのみを起動します;

• ネイティブホストは安定した拡張機能ID以外のオリジンを拒否します;

• MCPエンドポイントは 127.0.0.1 にのみバインドします;

• トンネルは送信専用です;

• アクションは通常のHTTP(S)タブに限定され、任意のJavaScript、デバッガーアクセス、Cookie、ブラウザストレージを公開しません;

• 曖昧な人間可読ターゲットは推測ではなく拒否されます。

無人使用の前に THREAT_MODEL.md と SECURITY_REVIEW.md を読んでください。

既知の制限

• 一度に1つのChromeプロファイルが拡張機能を読み込む必要があります。2つのプロファイルがポート 2091 を競合する可能性があります。

• Chrome内部ページ、Chrome Webストアページ、file:// ページ、シークレットタブは読み取りまたは制御できません。

• クロスオリジンのiframeはトラバースされません。

• CanvasのみのアプリケーションとChromeの組み込みPDFビューアーは、セマンティックテキストをほとんど返さない場合があります。

• 抽出器は、プライマリドキュメントの表示テキスト、見出し、リンク、説明を返しますが、生のHTMLは返しません。URL資格情報とフラグメントは削除され、機密性の高いクエリパラメータは編集されます。

• press_key はDOMキーボードイベントを使用します。EnterとEscapeには明示的な一般的なケースの動作がありますが、一部のサイトでは信頼されたOS/CDPキーボード入力が必要です。

• ChatGPT子エージェントの送信は、ChatGPTの現在のWebコンポーザー（#prompt-textarea）と送信ボタンのマークアップに依存します。将来のChatGPT UIの変更により、これらのセレクターを更新する必要がある場合があります。

• read_chatgpt_agent は子タブの表示セマンティックページテキストを返しますが、特権のあるChatGPT API応答は返しません。

• ファイルアップロードは意図的に実装されていません。一般的に行うには、より強力なファイルシステム/デバッガーサーフェスが必要になるためです。

開発

npm ci
npm run version:check
npm run typecheck
npm run lint
npm test
npm run artifacts:check
npm run test:e2e
npm audit