agent-browser-mcp

あなたのAgentが「現在使用中のリアルなChrome」を直接操作できるようにするMCPサービスです。

これはサンドボックス化されたブラウザや単純なウェブスクレイパーではなく、PC上で既に開いているChromeに接続するため、以下を保持します：

ログイン状態
Cookies
開いているタブ
リアルなページコンテキスト

次のようなシナリオに適しています：

Hermesに小紅書（Xiaohongshu）、管理システム、ナレッジベース、管理コンソールページを直接読み取らせる
ステートレスなブラウザで再ログインするのではなく、既にログイン済みのサイトで自動化を行う
通常のブラウザ自動化が不安定な場合に、CDP / リアルなマウス・キーボード操作に切り替える
1つのMCPツールで、ページスキャン、JS実行、CDP制御、スクリーンショット、物理入力をすべて利用する

一言で言えば：

これは「リアルなブラウザ自動化」を標準的なMCPとしてパッケージ化したプロジェクトであり、Agentがサンドボックスブラウザを操作するだけでなく、あなたの日常的なブラウザワークフローに真に入り込めるようにします。

主な機能一覧

リアルなChromeタブの検出と切り替え
ページスキャンと簡略化されたコンテンツ抽出
ページ内JavaScript実行
ネイティブCDPの単一コマンド / バッチ呼び出し
ページスクリーンショット / デスクトップスクリーンショット
Cookiesの読み取り
マウス移動、クリック、ドラッグ
キーボード入力とホットキー

Hermes、Claude Desktop、CursorなどのMCPクライアントから、PC上のリアルなブラウザを直接操作したい場合、このプロジェクトが最適です。

このMCPでできること

このプロジェクトは、リアルなブラウザ自動化機能を標準的なMCPツールとしてパッケージ化しており、主な機能は以下の通りです：

1. ブラウザタブとナビゲーション

現在接続されているリアルなタブの確認
指定したタブへの切り替え
現在のタブでURLを開く
新しいタブを開く

2. ページの読み取り

現在のページコンテンツのスキャン
簡略化されたHTML / テキストの抽出
情報フィード、投稿リスト、検索結果ページの読み取りに最適

3. ページ実行とCDP制御

ページ内での任意のJavaScript実行
Chrome DevTools Protocol (CDP) の直接呼び出し
単一コマンドおよびバッチコマンドのサポート
スクリーンショット、DOMクエリ、クリック、ファイルアップロードなどの複雑な操作に使用可能

4. スクリーンショット機能

ページスクリーンショット（CDP経由）
デスクトップスクリーンショット（リアルなデスクトップ操作の補助用）

5. リアルな物理入力

マウス移動
マウスクリック
マウスドラッグ
キーボード入力
ホットキー送信

これらの機能は、以下のような処理に非常に適しています：

ログイン状態の維持が必須のサイト
通常のブラウザ自動化ツールでは風評リスク（検知）されやすいサイト
リアルなクリック / リアルなキーボード入力が必要なシナリオ
複雑なページ構造を読み取る必要があるシナリオ

適したシナリオ

例えば：

Hermesを使って現在の小紅書のホームのおすすめフィードを読み取る
リアルなブラウザで管理ページを開いて情報を取得する
CDPを呼び出してページのスクリーンショットを撮る
ページ内のJSで不十分な場合に、リアルなマウス/キーボード操作にフォールバックする
ステートレスなブラウザで再ログインするのではなく、既にログイン済みのサイトをAgentに直接操作させる

動作原理

プロジェクトは3つの層で構成されています：

Chrome拡張機能

リアルなウェブページに注入
Chrome APIを通じてtabs / cookies / debugger / managementにアクセス
ローカルブリッジサービスと通信

TMWebDriver ローカルブリッジ

デフォルトのリスニング：
- WebSocket: 127.0.0.1:18765
- HTTP: 127.0.0.1:18766
拡張機能の接続、セッションの維持、実行結果の転送を担当

MCPサービス

ブラウザ機能をMCPツールとして公開
Hermes、Claude Desktop、Cursorなどのクライアントから直接呼び出し可能

主要ツール

現在公開されている主なMCPツールは以下の通りです：

ブラウザ/タブ

get_setup_status
list_tabs
switch_tab
open_url
open_new_tab
extension_path
list_extensions

ページの読み取り/実行

scan_page
execute_js

CDPとスクリーンショット

cdp_command
cdp_batch
get_cookies
capture_page_screenshot
capture_desktop_screenshot

物理入力

mouse_move
mouse_click
mouse_drag
type_text
hotkey
pointer_info

インストール要件

推奨環境：

macOS または Windows
Python 3.10+
Google Chrome
MCPをサポートする任意のクライアント（例：Hermes Agent、Claude Desktop、Cursor）

インストール

ローカルにクローンした後、以下を実行します：

cd agent-browser-mcp
pip install -e .

wheelをビルドしてからインストールしたい場合：

python -m pip install --upgrade build
python -m build
pip install dist/agent_browser_mcp-0.1.0-py3-none-any.whl

コマンドラインツール

インストール後、CLIが提供されます：

agent-browser-mcp

よく使われるサブコマンド：

Chrome拡張機能ディレクトリの出力

agent-browser-mcp extension-path

Hermes設定スニペットの出力

agent-browser-mcp print-hermes-config

環境診断

agent-browser-mcp doctor

このコマンドはJSONを出力し、以下の確認を支援します：

拡張機能ディレクトリの場所
config.js が生成されているか
ポートの状態
現在接続されているタブの数
次のステップへのアドバイス

Chrome拡張機能のインストール

このプロジェクトにはアンパックされたChrome拡張機能が含まれており、手動で一度読み込む必要があります。

ステップ1：拡張機能ディレクトリの取得

agent-browser-mcp extension-path

ステップ2：Chromeで読み込む

以下を開きます：

chrome://extensions

次に：

「デベロッパーモード」をオンにする
「パッケージ化されていない拡張機能を読み込む」をクリック
前のステップで出力されたディレクトリを選択

ステップ3：通常のウェブページを開く

about:blank のままにしないでください。

Chromeで通常のウェブページを開いてください。例：

https://www.baidu.com
https://www.xiaohongshu.com

そうしないと、有効なセッションが確立されません。

Hermesの設定

以下のセクションを ~/.hermes/config.yaml に追加してください：

mcp_servers:
  agent_browser:
    command: agent-browser-mcp
    timeout: 120
    connect_timeout: 60

プロジェクトにはサンプルファイルも同梱されています：

examples/hermes-config.yaml

設定後、Hermesを再起動するか、MCPを再読み込みしてください。

以下のコマンドで検証可能です：

hermes mcp list
hermes mcp test agent_browser

テストが成功すれば、Hermesはこれらのブラウザツールを検出して呼び出せるようになります。

Claude Desktop / Cursorの設定

リポジトリにはサンプルも用意されています：

examples/claude-desktop-config.json
examples/cursor-mcp.json

設定構造は非常にシンプルで、核心は以下の通りです：

{
  "mcpServers": {
    "agent_browser": {
      "command": "agent-browser-mcp",
      "args": []
    }
  }
}

一般的な使用フロー

Pythonパッケージのインストール
Chromeで拡張機能を読み込む
通常のウェブページを開く
MCPクライアントでこのサービスに接続
ブラウザツールの呼び出しを開始

例えば、Agentは以下のようなことができます：

小紅書のホームを開く
おすすめフィードを読み取る
投稿リストをスキャンする
ページをCDPでスクリーンショットする
必要に応じてリアルなマウス/キーボード操作を実行する

セキュリティ上の注意

このプロジェクトは、あなたのリアルなブラウザとリアルなデスクトップを操作します。

つまり：

マウスの移動は本物です
クリックは本物です
入力は本物です
ホットキーは本物です
ブラウザ内のログイン状態も本物です

信頼できるMCPクライアントおよびAgent環境でのみ使用してください。

よくある質問

1. HermesはMCPサービスを認識しているが、どのタブにも接続されていない

以下を確認してください：

拡張機能が chrome://extensions で読み込まれているか
Chromeで通常のウェブページが開かれているか
about:blank のままになっていないか

以下を実行することもできます：

agent-browser-mcp doctor

2. `connected_tabs` が 0 になる

通常、以下のいずれかが原因です：

拡張機能が正常に読み込まれていない
現在、通常のウェブページが開かれていない
拡張機能を再読み込みしたばかりで、ページが更新されていない

推奨：

現在のウェブページを更新する
新しい通常のURLを開く
doctor をもう一度実行する

3. macOSで物理入力が機能しない

ターミナル / MCPクライアントにシステム権限を付与してください：

アクセシビリティ（Accessibility）
画面収録（デスクトップスクリーンショットが必要な場合）

4. `hermes mcp test agent_browser` が失敗する