DOMShell

@apireno/domshell

ブラウザーをファイルシステムに変える MCP サーバーです。AI エージェントは ls、cd、grep、find、click、type を使って、Linux ファイルシステムを操作するのと同じようにウェブを閲覧します。

DOMShell は Chrome のアクセシビリティツリーを仮想ファイルシステムにマッピングします。すべての DOM 要素がファイルまたはディレクトリになります。エージェントは、生のセレクターや座標ではなく、使い慣れたコマンドで操作できます。

インストール

DOMShell には3 つのインストール方法があります。環境に合ったものを選んでください。方法 1 がドキュメントで案内しているデフォルトで、99％のユーザーにおすすめです。方法 2 と 3 は、複数の MCP サーバーにまたがるライフサイクル管理が必要な場合に利用できます。

方法 1 — ネイティブ CLI（デフォルト、最も簡単）

npm install -g @apireno/domshell

インストールせずに直接実行することもできます。

npx @apireno/domshell

Node 18 以降を使用すれば、macOS、Linux、Windows で動作します。ほかに必要なものはありません。

方法 2 — Docker 化（任意）

コンテナーで DOMShell を実行します。Node をグローバルにインストールしたくない場合や、プロセスを分離したい場合に便利です。Docker Desktop が必要です。トークンは Git で無視される .env ファイルに保存されるため、コンテナーの再起動やホストの再起動後も維持されます。

git clone https://github.com/apireno/DOMShell && cd DOMShell/mcp-server
cp .env.example .env
# Edit .env and set DOMSHELL_TOKEN to: $(openssl rand -hex 24)
docker compose build      # produces domshell-mcp-server:latest
docker compose up -d
docker compose logs -f

コンテナーはポート 3001（MCP HTTP）と 9876（Chrome 拡張機能への WebSocket ブリッジ）をループバックインターフェイスにマッピングするため、Chrome 拡張機能はネイティブインストールの場合とまったく同じように接続できます。restart: unless-stopped により、Docker Desktop の起動時にコンテナーも自動的に再起動します（方法 2 で再起動後も確実に動作させるには、Docker Settings で「ログイン時に Docker Desktop を起動」を有効にしてください）。

方法 3 — ToolHive 管理（任意）

ToolHive（thv）を使うと、実行中のほかの MCP サーバーと合わせてコンテナーのライフサイクルを管理できます。方法 2 と同じ .env ファイルを使用し、thv がその内容を読み込みます。

brew tap stacklok/tap && brew install thv      # one-time
cd DOMShell/mcp-server
cp .env.example .env       # edit DOMSHELL_TOKEN if you haven't already
docker compose build       # produces domshell-mcp-server:latest

thv run \
  --name domshell-mcp-server \
  --transport streamable-http \
  --target-port 3001 \
  -p 9876:9876 \
  --env-file .env \
  domshell-mcp-server:latest

thv list                          # workload status (URL on the proxy port)
thv logs domshell-mcp-server      # tail logs

--target-port 3001 によってポートがホストのループバックに自動公開されるため、コンテナーには http://127.0.0.1:3001/mcp で接続できます。既存の MCP クライアント設定（Claude Desktop、Cursor、…）は変更せず、そのまま動作します。

方法 3 では、再起動時の自動起動に launchd エージェントを一度設定する必要があります（方法 2 は Docker Desktop だけで再起動後も動作します）。再起動時の動作をまとめた表、launchd plist テンプレート、自動起動スクリプト、再起動のシミュレーションによる検証については、docs/deploy/container-and-toolhive.md を参照してください。

Chrome 拡張機能（3 つすべての方法で必須）

DOMShell Chrome Extension も必要です。MCP サーバーは、この拡張機能を通じてブラウザーと通信します。

クイックスタート

npx @apireno/domshell init

セットアップウィザードがインストール済みの MCP クライアント（Claude Desktop、Cursor、Windsurf）を検出し、セキュアなトークンを生成して設定を書き込みます。非対話モードでは --yes を使ってください。

続いて、次の手順を実行します。

1. DOMShell Chrome Extension をインストールします
2. Chrome のサイドパネルを開き、DOMShell セッションを開始します
3. MCP クライアントを再起動すると、DOMShell のツールが表示されます
4. DOMShell ターミナルで connect <token> を実行します（トークンはウィザードに表示されます）

Claude Desktop の設定

Claude Desktop の MCP 設定（claude_desktop_config.json）に、次の内容を追加します。

{
  "mcpServers": {
    "domshell": {
      "command": "npx",
      "args": ["-y", "@apireno/domshell", "--allow-write"]
    }
  }
}

stdio プロキシを使う場合（クライアントが command/args 形式を必要とする場合に必須）：

{
  "mcpServers": {
    "domshell": {
      "command": "npx",
      "args": ["-y", "-p", "@apireno/domshell", "domshell-proxy", "--port", "3001", "--token", "YOUR_TOKEN"]
    }
  }
}

ベンチマーク

基盤モデルにどちらも Claude を使用し、ウェブタスク 4 件を各 8 回試行して、DOMShell と Computer-in-the-Cloud（CiC）を比較しました。

指標	DOMShell	CiC
タスクあたりの平均 API 呼び出し数	4.3	8.6
最難関タスク（T4）	6.0 回	13.0 回
コールドスタートと CiC のウォームキャッシュの比較	4.5 回	5.5 回

DOMShell は同じタスクを完了するための API 呼び出しを2 分の 1 に削減します。ファイルシステムというメタファーによってモデルがページの全体像を把握できるため、探索に費やす時間が減り、情報の抽出により多くの時間を使えます。

実験データの全容：experiments/claude_domshell_vs_cic

MCP インターフェース

デフォルト（推奨）：単一の domshell_execute ツール。 DOMShell コマンドを文字列で渡します（"ls"、"cd tabs/123"、"open https://example.com" など）。または、複数のコマンドを改行で区切って渡せば、ワークフロー全体を1回の呼び出しで実行できます。ツールは1つ、承認も1回で、ツールの説明にコマンド一式が記載されています。

複数行のセマンティクス： command に改行が含まれる場合、各行は同じ MCP セッションおよびレーン内で順番に実行されます。そのため、行の間で cwd、環境変数、履歴が保持されます。ある行でエラーが発生しても、残りの処理は停止しません。エラーメッセージは統合された出力に含まれ、後続の行も実行されます。これは "cd path\ngrep pattern\ncd back" のような、クリーンアップ行を含むイディオムに適しています。途中の処理でエラーが発生しても、最後の復元処理が実行されるためです。実装：mcp-server/index.ts:1115-1136。

レーンとマルチエージェント。 すべての応答は [lane: <id>] で終わります。複数の MCP クライアントを同時に接続でき、それぞれが独立した Chrome タブグループを使用します。1つのクライアント内にサブレーン（例：Claude Desktop の2つのチャット）を作成するには、最初の呼び出しで group_id: "new" を渡し、その後は返された ID を使い続けます。CHANGELOG.md を参照してください。

詳細モード — --granular

サーバーを --granular で起動すると、コマンドごとの38個のツールが domshell_execute と併せて公開されます。クライアント UI で操作ごとに承認したい場合に使用します。

読み取りティア（常に利用可能）： ls、cd、pwd、cat、find、grep、tree、text、read、tabs、here、refresh、diff、eval、functions、watch、for、script、each、extract_links、extract_table

書き込みティア（--allow-write）： click、focus、type、scroll、navigate、open、submit、back、forward、close、select、js、screenshot、wait、call

機密ティア（--allow-sensitive）： whoami

CLI フラグ

フラグ	説明
--allow-write	書き込みティアのツールを有効にします（click、type、navigate など）
--allow-sensitive	機密ティアのツールを有効にします（whoami）
--allow-all	すべてのティアを有効にします
--granular	コマンドごとの38個のツールを domshell_execute と併せて公開します
--port N	WebSocket ポート（デフォルト：9876）
--mcp-port N	HTTP MCP ポート（デフォルト：3001）
--domains a.com,b.com	指定したドメインに制限します
--token TOKEN	認証トークンを設定します（省略時は自動生成）
--log-file PATH	監査ログの保存先（デフォルト：audit.log）
--confirm	書き込みの前に、サーバーのターミナルで操作ごとの y/n 確認を有効にします。デフォルトでは無効です。
--no-confirm	何もしません（後方互換性のために保持されています。操作ごとの確認はデフォルトで無効です）。

セキュリティ

すべてのコマンドは、4段階のセキュリティモデルを通過します。

• 読み取り — 常に許可されます（ls、find、grep、text）
• ナビゲーション — --allow-write が必要です（navigate、open、back、forward）
• 書き込み — --allow-write が必要です（click、type、js、select）
• 機密 — --allow-sensitive が必要です（whoami、Cookie へのアクセス）

すべてのコマンドは監査ファイルに記録されます。ドメイン許可リストにより、エージェントがアクセスできるサイトを制限できます。認証トークンで HTTP エンドポイントを保護します。

アーキテクチャ

MCP Client (Claude, Cursor, etc.)
    ↓ HTTP :3001/mcp
DOMShell MCP Server (Express + WebSocket)
    ↓ WebSocket :9876
DOMShell Chrome Extension (CDP 1.3)
    ↓ Chrome Debugger Protocol
Browser DOM + Accessibility Tree

リンク

• Chrome ウェブストア：pireno.com/domshell
• GitHub：github.com/apireno/DOMShell
• ブログ：ブラウザー用ファイルシステムを構築した理由
• プロジェクトホーム：pireno.com/domshell

Pireno が開発しました。

ライセンス

MIT