glovebox-mcp

glovebox-mcp

サンドボックス化されたコンピューター操作 MCP サーバー — AI エージェントが実際のブラウザーやデスクトップアプリを操作できるようにします （マウス、キーボード、スクリーンショット、ビジョンによる位置特定）。ネストされた X11 ウィンドウ内に隔離されるため、 実際の画面、ファイル、その他のアプリに触れることはありません。

実験室のグローブボックスのように、エージェントが内部に手を入れて実際のアプリケーションを操作し、ほかのすべてから隔離します。サンドボックスを起動し、自動化したいサイトやアプリにそのウィンドウ内でログインすると、エージェントはその中だけで操作します。動作をリアルタイムで確認でき、すぐに閉じることもできます。

Model Context Protocol に対応しているため、Claude Code などの MCP クライアントで動作します。ホストで Wayland を実行していても、サンドボックスはエージェントが操作できる実際の X サーバーを提供します。

_{サンドボックス内でエージェントが実際のブラウザーを操作 — カーソルを滑らかに動かし、Unicode の名前（Nadja Kovačič）を挿入し、文字を入力して送信します。すべてネストされた X11 ウィンドウ内に隔離されています。}

ネストされた X11 サンドボックスが必要な理由

• デスクトップ自動化の多く（xdotool、PyAutoGUI）はX11 専用ですが、最新のデスクトップの多くはWaylandで動作しています。
• Xephyr は、単一のウィンドウ内（DISPLAY :1）に実際の X サーバーを提供します。エージェントの操作はすべて — クリック、文字入力、スクリーンショット — そのウィンドウ内に隔離され、実際のデスクトップには影響しません。
• 操作の主導権はあなたにあります。動作をリアルタイムで確認し、pkill Xephyr ですべてを閉じられます。

必要条件

• Linux — サンドボックスは実際の X サーバー（Xephyr）をネストするため、Wayland ホスト上でも動作します （Xwayland 経由）。macOS／Windows には対応していません。Ubuntu で開発されていますが、以下のパッケージがあれば最新の Linux で動作します。
• Python 3.10+ と uv（仮想環境で使用）。
• システムパッケージ — xserver-xephyr（Xephyr）、openbox、scrot、x11-utils、xdotool、 wmctrl、xclip（basic では tesseract-ocr も必要）。Debian／Ubuntu ではインストーラーが apt 経由で自動インストールします（sudo が必要）。Fedora／Arch では、対応する dnf／pacman コマンドを表示します。MCP サーバー自体はディストリビューションに依存しないため、これらのツールがあればどの Linux でも動作します。
• サンドボックス内のブラウザー（Chromium または Chrome）。
• NVIDIA GPU（VRAM ≥6 GB） — local ビジョンモードでのみ必要です。

インストール

ビジョンバックエンドを選び、対応するワンライナーを実行します（クローン → インストール）。いずれもシステムパッケージ （Debian／Ubuntu では apt 経由で自動インストール）と、そのモード用の Python 依存関係をインストールし、パスを設定済みのすぐに貼り付けられる mcp-config.json を作成します。

none — ローカルモデルなし。エージェントがスクリーンショットを自分で読み取ります（最軽量、即時利用可能）：

git clone https://github.com/segentic-lab/glovebox-mcp && cd glovebox-mcp && ./install.sh none

basic — Tesseract OCR による位置特定（parse_screen → テキスト + 座標、CPU のみ）：

git clone https://github.com/segentic-lab/glovebox-mcp && cd glovebox-mcp && ./install.sh basic

local — NVIDIA GPU 上の OmniParser（parse_screen → テキスト + アイコン、ピクセル単位で正確。重みは約 4 GB、VRAM ≥6 GB）：

git clone https://github.com/segentic-lab/glovebox-mcp && cd glovebox-mcp && ./install.sh local

選択したモードは .vision-mode に書き込まれます（実行ごとに GLOVEBOX_VISION 環境変数で上書きできます）。

あらゆる MCP クライアント／ハーネスで動作

Claude Code、Cursor、Codex、自作のエージェントなど、標準的な MCP サーバーなので、特定のホストに依存しません。 互換性に関する注意点は 2 つあります。basic／local は要素の座標をテキストとして返すため、テキストのみを扱うエージェントでも動作します。none は、クライアントがツールのスクリーンショットをマルチモーダルモデルに渡すことを前提とします（Claude Code、Cursor、その他の画像対応 MCP クライアントで問題なく動作します）。

クイックスタート

1. サンドボックスを起動します（起動したままにします）。

   ./start-display.sh              # 1440×900 Xephyr window with a browser
   ./start-display.sh 1920x1080    # …or pass a screen size (or set $RES)
   

   自動化したいサイトやアプリにそのウィンドウ内でログインします。
2. MCP クライアントにサーバーを登録します。install.sh はインストール先の実際のパスを設定した mcp-config.json をすでに作成しています。glovebox ブロックをクライアントの MCP 設定にコピーします。

   { "mcpServers": { "glovebox": {
       "command": "/abs/path/to/glovebox-mcp/.venv/bin/python",   // filled in by install.sh
       "args":    ["/abs/path/to/glovebox-mcp/server.py"],
       "env":     { "DISPLAY": ":1" }
   } } }
   

   サーバーを読み込ませるため、クライアントを再起動します。
3. エージェントにスクリーンショットの撮影、クリック、文字入力を指示します。操作は :1 ウィンドウ内だけで行われます。

AI エージェントで操作しますか？ AGENTS.md をエージェントのシステムプロンプトに貼り付けてください。観察 → 操作 → 検証のループ、位置特定、アップロード／Unicode に関する注意点、操作を止めるタイミングを説明しています。

ツール

ツール	内容
status()	サーバーとサンドボックスの状態を読み取り専用でまとめて取得します。バージョン、ビジョンバックエンド、ホストのディスプレイ、稼働中のインスタンス、およびシステム依存関係（xdotool、xclip、Xephyr、tesseract、OmniParser の重み）が揃っているかを確認できます。最初に実行し、バグ報告に結果を貼り付けてください。
parse_screen()	ビジョンによるグラウンディングを行い、検出した要素（id、type、label、interactive、ピクセル中心座標）を JSON で返します（1 回につき最大 300 件。"truncated" で切り詰められたことを示します）。さらに、番号付き Set-of-Mark 画像を /tmp/glovebox_annotated_<N>.png に出力します。（local モード：GPU で OmniParser を実行し、約 2 秒です。）
click_element(id)	直前の parse_screen で検出した要素をクリックします（座標を推測する必要はありません）。
screenshot()	インスタンスのスクリーンショットを取得します。
click(x,y) · move_mouse · scroll · drag · double_click	ポインター操作です。
type_text(text)	Unicode 対応の文字入力です（ASCII は xdotool で入力します。č/š/ž などを含む文字列はクリップボード経由で挿入します。これは、一部の GTK アプリでは xdotool の合成 Unicode 入力が通知なく無視されるためです）。
press_keys("ctrl+a"/"Return"/…)	キーやキーの組み合わせを入力します（xdotool 構文）。
upload_file(filepath, selector?)	Chrome DevTools Protocol 経由で、ローカルファイルをページの <input type=file> に添付します。X11 のファイル選択ダイアログは自動化から見えず、レンダラーもハングするため、すべてのアップロードでこのツールを使用してください。アップロードボタンをクリックしてダイアログを開こうとしてはいけません。launch_app／start-display.sh で起動した Chromium で動作します（これらはインスタンスごとに --remote-debugging-port、9222+N を開きます）。ブラウザーのファイル入力欄のみに対応します。ネイティブアプリについては open_file を参照してください。
open_file(filepath, app?)	インスタンスのディスプレイ上で、ローカルファイルをネイティブアプリ（例：app="gimp"）または xdg-open で開きます。GTK アプリには launch_app と同じ X11／D-Bus 処理が適用されます。
list_files()	インストールディレクトリ内にあるインスタンスのステージングフォルダー files/<N>/ と、その内容を一覧表示します。
launch_app(command, name?, size?) · list_instances() · close_instance(n)	複数インスタンスを制御します（下記参照）。
wait_ms(ms) · get_screen_size()	待機時間／サンドボックスのサイズを取得します。

すべての制御ツールは instance=N と、任意の observe ／ settle_ms を受け取ります（下記参照）。 local モードでは、最初の parse_screen 呼び出し時に OmniParser が遅延読み込みされます（初回は約 6 秒、その後は解析 1 回につき約 2 秒です）。

構造化された、正確な応答

すべてのツールは JSON を返します：{"ok": true, "action": "click", "instance": 1, "detail": "clicked (10,20) button 1", …}。 失敗時は MCP の isError フラグが設定され、同じ形式の JSON がエラーテキストに埋め込まれて返されます ——{"ok": false, "error": "…", "fix": "…"}。このとき fix には、問題を解消する呼び出しが示されます （例：停止中のインスタンスをクリックすると list_instances() ／ launch_app() の実行が指示されます。不明な要素 id の場合は parse_screen() の再実行が指示されます）。何も起きない操作も失敗として扱われます。無効な keysym、スクロール量が 0 のスクロール、実行中でないインスタンスの終了、xclip を使わない非 ASCII 文字の入力は、成功したように見せかけずエラーになります。screenshot() は PNG 画像を返します。observe="screenshot"|"parse" は、1 回の呼び出しで [json, image] を返します。

ビジョンバックエンド（選択可能）

GLOVEBOX_VISION 環境変数、.vision-mode ファイル、またはデフォルトの local で指定します。

モード	parse_screen	必要なもの	用途
none	無効（注記を返します）。screenshot() と理由を使用してください	不要（mcp、mss、xdotool）	最軽量。エージェント自身のビジョンでグラウンディングを行います
basic	Tesseract OCR → テキスト要素と座標	tesseract-ocr + pytesseract	GPU がない場合。テキストのみでグラウンディングします
local	OmniParser → テキストとアイコン、および座標	torch + CUDA + OmniParser の重み	最適なグラウンディング

./install.sh <mode> でいつでも切り替えられます（そのモードに必要なものだけをインストールします）。

マルチインスタンス（アプリウィンドウのフリート）

各制御ツールは instance=N を受け取ります（デフォルトは 1 = start-display.sh のサンドボックスです）。インスタンスを追加すると、それぞれ独立した Xephyr ディスプレイ／ウィンドウがホストのデスクトップ上に起動します。

• launch_app(command, name?, size?) → 次に空いている :N で 任意の GUI アプリ（ chromium、gimp、inkscape、xterm など）を起動します。Chromium には、X11 フラグ、インスタンスごとのプロファイル、リモートデバッグポート、D-Bus の分離が自動的に設定されます。インスタンス ID を返します。
• list_instances() · close_instance(n)。

各ディスプレイには専用のカーソルがあるため、複数のエージェントがそれぞれ別のインスタンスを操作し、並行して作業できます（各エージェントにつき 1 ウィンドウ）。共有リソースは、local モードの parse_screen が使う GPU だけです（処理はキューに入ります）。 新しいウィンドウを表示するホストのディスプレイは GLOVEBOX_HOST_DISPLAY（デフォルトは :0）です。XAUTHORITY は自動検出されます。

1 回の呼び出しで操作と画面確認

click · click_element · type_text · press_keys · scroll · drag · double_click は observe（デフォルトは none · screenshot · parse）と settle_ms を受け取ります。observe="screenshot" を指定すると、操作結果と操作後の画面を 1 回の呼び出しで返します（settle_ms でページの更新を待機します）。別途スクリーンショットを取得する必要はありません。デフォルトの none なら通常の手順を低コストに保てます。ページが変わる操作（ページ移動、送信など）では screenshot／parse を指定してください。

ファイルとアップロード

各インスタンスには、インストールディレクトリ内にステージング用フォルダー files/<N>/ が用意されます。これはそのインスタンス専用の安定したファイル配置場所です（ネイティブアプリから読み取れるほか、$HOME の下にあるため snap 版 Chromium からも読み取れます）。 list_files(instance) でフォルダーとその内容を確認できます。

• ブラウザーの <input type=file> → upload_file(path, instance)（CDP 経由）。入れ子になったファイル選択ダイアログは自動化から見えず、snap 版 Chromium が応答しなくなるため、ダイアログを開く目的でアップロードボタンをクリックしないでください。
• ネイティブアプリ（GIMP、Inkscape、エディター）→ open_file(path, instance, app="gimp") を使うか、アプリ独自の ［開く］ダイアログを操作してください。ブラウザーのものとは異なり、実際に表示されるウィンドウなので、パスを入力できます（GTK のファイル選択ダイアログでは Ctrl+L）。
• 保存／ダウンロード → アプリは自分のユーザーとして実行されるため、書き込み可能な場所ならどこにでも保存できます。launch_app で起動した Chromium インスタンスは、ダウンロードと［名前を付けて保存］の保存先が files/<N>/ に設定済みです。ネイティブアプリの［保存］ダイアログでも同じ場所を指定し、list_files(instance) で結果を確認してください。

メンテナンス（local モード）

install.sh は OmniParser をクローンし、v2 の重みをダウンロードして、以下の 2 つのパッチを自動的に適用します。

• PaddleOCR をオプション化（easyocr を使用します）：OmniParser/util/utils.py の from paddleocr import PaddleOCR を try/except で囲み、モジュールレベルの paddle_ocr = PaddleOCR(...) を … if PaddleOCR is not None else None でガードします。
• transformers のバージョンを 4.49.0 に固定 — これより新しいリリースでは Florence-2 のリモート設定が動作しなくなります。

OmniParser を手動でアップグレードした場合は、PaddleOCR のパッチを再適用してください。重みは OmniParser/weights/ にあります。

停止

pkill Xephyr      # closes the sandbox (browser + WM + display)

安全性

• エージェントの入力と視覚情報はサンドボックスのディスプレイに限定されます。実際のデスクトップを見たり操作したりすることはありません。
• サーバープロセスはユーザー権限で実行されます（シェル／ファイルへのアクセスがあり、他の MCP サーバーと同様です）。サンドボックス化されるのは、Xephyr ウィンドウに対するGUI 操作のみです。ファイルを OS レベルで分離するには、VM またはコンテナー内で実行してください。
• すべての動作をリアルタイムで確認でき、pkill Xephyr ですぐに終了できます。
• 責任を持って自動化してください。利用するのは、使用を許可されているサイトやサービスに限ってください。

ファイル

• server.py — MCP サーバー（すべてのツール）。
• install.sh — モード対応インストーラー（none／basic／local）。
• start-display.sh — Xephyr サンドボックス（ディスプレイ＋ウィンドウマネージャー＋ブラウザー）を起動します。
• AGENTS.md — AI エージェント向けのすぐに使えるツール操作手順（システムプロンプトに貼り付けてください）。
• mcp-config.json — すぐに貼り付けて使える MCP クライアント設定スニペット。

クレジット

local ビジョンモードでは、Microsoft の OmniParser を使用しています （install.sh によってクローンされ、重みがダウンロードされます。独自のライセンスが適用されます）。画面キャプチャには mss を使用し、入力操作には xdotool を使用しています。Microsoft とは提携していません。

コントリビューション

MIT ライセンスのもと、現状のまま提供されています。Issue や PR は歓迎しますが、メンテナンスは一人で行っています。 サポートや返信までの時間は保証されません。 役に立った場合は、⭐ を付けていただけると励みになります。

ライセンス

MIT — LICENSE を参照してください。