Docker¶

掲載されている画像は、MCPを安定して繰り返し使用するための推奨実行環境です。

実行¶

docker run --rm -i \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

アーティファクトは、コンテナ内の /data に書き込まれます。このパスをマウントして、スクリーンショット、スナップショット、ダウンロードしたファイル、およびネットワーク出力を保存してください。

イメージはすでに Tini を PID 1 および subreaper として実行しているため、通常のコマンドに追加の Docker init プロセスは不要です。

Headed セッション、health check、制限された runtime¶

headless: false では、コンテナは必要に応じてプライベートな Xvfb を起動し、コンテナ終了まで維持します。これは可視デスクトップでも VNC、noVNC、RDP、host X11、画面キャプチャのサービスでもありません。Playwright の context、page、profile、artifact は分離されますが、ネイティブ X11 の focus、clipboard、画面キャプチャは tenant 分離の境界ではありません。Docker health check はプライベート Unix socket で MCP CLI の event loop を確認し、Xvfb が起動済みならその可用性も確認します。MCP stdio 経由でトラフィックを送らず、/healthz や /readyz の代替でもありません。read-only root filesystem では /data をマウントし、headed セッションがあり得る場合は /tmp と /tmp/.X11-unix に writable tmpfs を用意してください。

同じリリースタグが、Docker Hub には swimmwatch/cloakbrowser-mcpという形式で公開され、GHCRにはghcr.io/swimmwatch/cloakbrowser-mcpという形式で公開されます。

永続プロファイル¶

Docker はデフォルトでは永続的なブラウザプロファイルを有効にしません。cookie、 ローカルストレージ、キャッシュ、または拡張機能の状態をコンテナ再起動後も保持したい場合は、 既存の /data ボリュームを永続化ルートとして使用してください：

docker run --rm -i \
  -e PLAYWRIGHT_MCP_USER_DATA_DIR=/data/profiles/default \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

Docker 内の環境変数には、ホストパスではなく /data/profiles/default のような コンテナパスを使用する必要があります。ブリッジはプロファイルディレクトリが存在しない場合に 作成し、書き込み可能であることを確認し、コンテナパスを生成済みの Playwright MCP 設定に書き込み、1 つのサーバープロセス内で重複するアクティブなプロファイルディレクトリを拒否します。

CloakBrowser ライセンスキャッシュ¶

このイメージは、CloakBrowser のバイナリ、ライセンス状態、検証キャッシュを /home/node/.cloakbrowser に保存します。コンテナを置き換えても GitHub 無料枠または Pro のログインを保持するには、ここに名前付きボリュームをマウントします。

docker volume create cloakbrowser-cache

docker run --rm -it \
  --entrypoint node \
  -v cloakbrowser-cache:/home/node/.cloakbrowser \
  swimmwatch/cloakbrowser-mcp:latest \
  /opt/cloakbrowser-mcp/node_modules/cloakbrowser/dist/cli.js login

docker run --rm -i \
  -v cloakbrowser-cache:/home/node/.cloakbrowser \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

保存済みのログインを確認または削除するには、同じボリュームでアップストリームの info または logout コマンドを使用します。代わりに、コンテナのシークレット管理 から CLOAKBROWSER_LICENSE_KEY を注入できます。ライセンスキーをイメージレイヤー、 バージョン管理に登録する Compose ファイル、またはビルド証拠として記録する コマンド出力に含めないでください。

カスタム CloakBrowser バイナリ¶

互換性のあるブラウザ実行ファイルをコンテナにマウントし、コンテナ内のパスを --binary-path（または CLOAKBROWSER_BINARY_PATH）で渡します。

docker run --rm --init -i \
  -v "$PWD/artifacts:/data" \
  -v "$PWD/custom-chrome:/browser/chrome:ro" \
  swimmwatch/cloakbrowser-mcp:latest \
  --binary-path /browser/chrome

このファイルはイメージの CPU アーキテクチャと互換性のある読み取り可能な Linux 実行ファイルであり、必要なライブラリがコンテナ内に存在する必要があります。この パスはコンテナ内のすべての Streamable HTTP セッションに適用されます。異なる ブラウザバイナリには別のコンテナを実行してください。

Chrome 拡張機能¶

Chrome 拡張機能には永続プロファイルが必要で、個別にマウントする必要があります。 環境変数にはホストパスではなくコンテナパスを使用してください。 拡張機能のマウントは読み取り専用にできます：

docker run --rm -i \
  -e PLAYWRIGHT_MCP_USER_DATA_DIR=/data/profiles/default \
  -e CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS=/extensions/my-extension \
  -v "$PWD/artifacts:/data" \
  -v "$PWD/extensions/my-extension:/extensions/my-extension:ro" \
  swimmwatch/cloakbrowser-mcp:latest

パスにカンマが含まれる場合、または複数の拡張機能ディレクトリを渡す場合は、 CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS に JSON 配列を使用してください。 拡張機能ファイルまたは拡張機能パスを変更した後は、コンテナを再起動してください。

Playwright Extension 接続モードは、上記の展開済み拡張機能のマウントとは別です。persistent Chrome/Edge profile に公式拡張機能をインストールし、PLAYWRIGHT_MCP_EXTENSION_TOKEN を指定する必要があります。各 profile を別々の writable path にマウントし、token は secret manager から渡してください。PLAYWRIGHT_MCP_EXTENSION=true と CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS は併用しないでください。

ストリーム可能なHTTP¶

ローカルでの Streamable HTTP を使用する場合は、コンテナのポートをループバックで公開してください：

docker run --rm -p 127.0.0.1:3000:3000 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000

curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz

コンテナから直接HTTPSにアクセスするには、証明書ファイルをマウントし、「HTTPS」を選択してください：

docker run --rm -p 127.0.0.1:3000:3000 \
  -v "$PWD/artifacts:/data" \
  -v "$PWD/certs:/certs:ro" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000 \
  --http-protocol https --https-cert /certs/cert.pem --https-key /certs/key.pem

ホスト側の 127.0.0.1:3000 バインドは、エンドポイントをローカルに保持します。 非ループバックインターフェースで Streamable HTTP を公開する場合、HTTPS と認証を使用するか、認証およびネットワーク制御機能を備えた信頼できる TLS ターミネーション型リバースプロキシの背後にサーバーを配置してください。 Streamable HTTP は、固定の GET /healthz および GET /readyz プローブを公開します。 --http-auth-token または CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN が設定されている場合、プローブには MCP リクエストと同じ Authorization: Bearer ... ヘッダーが必要です。 すべての HTTP トランスポートフラグおよび環境変数については、生成された CLI リファレンス を参照してください。

管理された CDP¶

構成された管理-CDP 範囲を一対一で公開します。この stdio の例では、一つを有効にします セッションとすべてのホストポートをループバックにバインドしたままにします:

docker run --rm -i \
  -p 127.0.0.1:9222-9231:9222-9231 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --cdp-enabled \
  --cdp-port-range 9222-9231 \
  --cdp-host 0.0.0.0 \
  --cdp-allow-remote \
  --cdp-advertised-host 127.0.0.1

--cdp-host 0.0.0.0はDockerのポートフォワーディングに必要なので、明示的な --cdp-allow-remoteのオプトインと具体的な--cdp-advertised-hostも必要です。 範囲を異なるホストポート番号に再マップしないでください: ディスカバリーURLには含まれています リースされたポートと各公開ポートは、それぞれ所有するセッションに一対一でルーティングする必要があります。

マルチセッション Streamable HTTP の場合、プールを設定して公開しますが、次を設定しないでください クライアントが個別にオプトインする場合のデフォルトの処理：

docker run --rm \
  -p 127.0.0.1:3000:3000 \
  -p 127.0.0.1:9222-9231:9222-9231 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http \
  --http-host 0.0.0.0 \
  --http-port 3000 \
  --cdp-port-range 9222-9231 \
  --cdp-host 0.0.0.0 \
  --cdp-allow-remote \
  --cdp-advertised-host 127.0.0.1

cdpEnabled: trueで認証されたinitializeリクエストは、1つの公開済みをリースします ポート。省略された値はプロセスのデフォルトを継承します、一方でcdpEnabled: false 明示的にオプトアウトし、CDPポートを消費しません。プールの枯渇は新しいもののみを拒否します CDP対応セッション；無効なセッションの容量を減らすことはありません。

cloakbrowser_bridge_infoから能力を持つURLを読み取ります。それを入れないでください コンテナのログまたはヘルスチェック。CDP API のようなものと接続します chromium.connectOverCDP()；URLはPlaywrightと互換性がありません chromium.connect() または現在の Open WebUI フロー。

--cdp-advertised-scheme https は公開された URL を https/wss に変更しますが、 ブリッジは、管理された CDP に対して TLS を提供しません。オペレーター所有の TLS ターミネーターを使用してください 外部ネットワーク名前空間で同じ宣伝されたポートを占有し、保持する Host/Origin、そしてプレーンテキストブリッジリスナーに一対一で転送します。 bridge-to-Chromiumホップもプレーンテキストのループバックトラフィックとして残ります。

GeoIPプロキシの照合¶

Docker は npm と同じプロキシおよび GeoIP 環境変数を使用します。地域ごとの QA において、CloakBrowser のタイムゾーン、言語、および ロケールのフィンガープリントを設定されたプロキシの場所に合わせる必要がある場合は、 GeoIP プロキシのマッチングを有効にしてください：

docker run --rm -i \
  -e PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
  -e CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

認証が必要なプロキシの場合は、プロキシのURLに認証情報を埋め込み、ユーザー名やパスワードに含まれる特殊文字をパーセントエンコードしてください。

対応する CloakBrowser バイナリはネイティブの URL 内インラインプロキシ認証を 使用し、古いバイナリは Playwright のプロキシオブジェクトにフォールバックします。

コンテナが Streamable HTTP を実行している場合、クライアントは initialize メタデータを通じて、MCP セッションごとに異なる プロキシを選択することもできます。 GeoIP プロキシのマッチング を参照して、実行時のプロキシメタデータ、 マルチリージョンでのユースケース、および制限事項について確認してください。

デフォルト設定¶

MCP クライアント設定¶

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/tmp/cloakbrowser-artifacts:/data",
        "swimmwatch/cloakbrowser-mcp:latest"
      ]
    }
  }
}

ローカルでビルドする¶

npm run docker:build
npm run docker:smoke

この Dockerfile では、ピン留めされた公式の Playwright MCP イメージをランタイムのベースとして使用し、ビルド中に利用可能な Debian のセキュリティ更新を適用し、ランタイムイメージから未使用のグローバル npm ペイロードを削除し、/opt/cloakbrowser-mcpの下にブリッジをインストールします。

このリリースワークフローでは、SBOMおよび出所証明を公開し、ソース、リビジョン、バージョン、ライセンス、ベースイメージ名、ベースイメージのダイジェストに関するOCIラベルを含め、公開前にTrivyを使用してビルド済みイメージをスキャンします。

追加の実用パス¶

upstream Playwright MCP とこのパッケージのどちらを使うかは比較を参照してください。短い作業手順にはレシピを使います: 永続プロファイル、拡張機能、reverse proxy、リージョン QA、Claude Desktop、Codex CLI、CI スモークテスト。