Go to Qiita Advent Calendar Top
LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@rakkyyy

WSLのDevContainerからCodexのChrome Devtools MCPとWindows上のChromeをつなげる

Last updated at Posted at 2025-10-19

WSL の DevContainer から 実ブラウザを操作する

chrome-devtools-mcp × Codex 導入ガイド

このガイドでは、Windows 側の Chrome を WSL の DevContainer から CDP（Chrome DevTools Protocol） で操作し、OpenAI Codex に chrome-devtools-mcp をつないで スクショ / DOM スナップショット / Console・Network / パフォーマンス計測 を実行できるところまでを、つまずきやすい点を全部つぶしながら手取り足取りで進めます。
（Windows 11 + WSL2 + Docker + VS Code Dev Containers 前提）

最初に

下記の記事を参考にさせていただきました。
DevContainerを用いないのであれば下記の記事がとても分かりやすいと思いますので是非見てみてください。
https://izumiz.me/posts/setup-wsl-chrome-devtools-mcp/

また、この記事は主にチャッピーにより作成されました。
とはいえ、内容自体は私とチャッピーで試行錯誤しながら実際に動作確認ができたモノになります。
不要な設定が紛れ込んでいる可能性も十分にあり得ますので、見つけましたらコメントいただければと思います。

備忘のためと少しでも誰かのためになればという思いで投稿いたします！参考になれば幸いです🙌

ゴールのイメージ

最終的に、Codex で /mcp を叩くと下のように chrome-devtools のツール一覧が並び、list_pages → select_page → navigate_page → take_screenshot 等が動きます。

/mcp

🔌  MCP Tools

  • Server: chrome-devtools
    • Status: enabled
    • Command: npx -y chrome-devtools-mcp@latest --browser-url=http://<IP>:9222
    • Tools: click, close_page, ... list_pages, navigate_page, take_screenshot, ...

0) 動作要件（最初に 1 分で確認）

  • Node.js v20.19 以上（DevContainer 内も 20+ 必須）［公式要件］。 (GitHub)
    node -v が v20.19+ であることを確認。
  • **Chrome（安定版）**がインストール済み。
  • VS Code の Dev Containers が使える（devcontainer.json で構成）。 (Visual Studio Code)

1) Windows で「デバッグ用 Chrome」を起動（別プロファイル）

**PowerShell（すべての Chrome を閉じた後）**で実行：

& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:TEMP\chrome-temp" `
  --no-first-run `
  --no-default-browser-check `
  --disable-extensions
  • --remote-debugging-port=9222 で CDP の HTTP/WS エンドポイントを開きます。 (Chrome for Developers)
  • セキュリティ上の理由から、既定プロファイルではなく --user-data-dir で 別プロファイルを使うのが推奨です（公式ガイド／README に記載）。

小ワザ：作業後は 必ず Chrome を完全終了し、netstat -ano | findstr :9222 で LISTEN が無いことを確認しましょう（安全運用）。

2) DevContainer を用意（Node 20 系 & Host 到達の安定化）

.devcontainer/devcontainer.json（例）：

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node
{
	"name": "Node.js & TypeScript",
	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
	"image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
	"runArgs": ["--add-host=host.docker.internal:host-gateway"],
	"features": {
		"ghcr.io/guiyomh/features/vim:0": {},
		"ghcr.io/jsburckhardt/devcontainer-features/codex:1": {}
	}
}
  • Node 20 系のベースイメージで 要件を満たす。 (Visual Studio Code)
  • --add-host=host.docker.internal:host-gateway で コンテナ → ホスト の到達を安定化（Docker Desktop の公式機能）。この値は /etc/hosts に IPv4 として追加されます。 (Docker Documentation)

DevContainer の仕組み・再ビルドは VS Code 公式を参照（設定を変えたら Rebuild 必須）。

3) ホスト IP（例: 192.168.65.254）の見つけ方

A. 最短手順：/etc/hosts を見る（runArgs が効いていれば出る）

grep host.docker.internal /etc/hosts
# 例）192.168.65.254  host.docker.internal  ← この IPv4 を控える

B. 出ない時の代替

  • DevContainer を Rebuild してから再度確認。 (Visual Studio Code)
  • それでも出なければ、host.docker.internal へ直接アクセスしてもうまくいくことはありますが、CDP は Host ヘッダの扱いが厳格で 500 になることがあるため、数値 IP 直がより安定です（後述）。これは Docker Desktop が “コンテナ→ホスト（実機）” を仲介してくれる仕組みの上に成り立っています。 (Docker Community Forums)

まとめ：**/etc/hosts に書かれた IPv4 が “あなたの環境の正解”**です（固定の 192.168.65.254 とは限りません）。

4) CDP の疎通テスト（HTTP → WS の順で確認）

以下、Step 3 で見つけた数値 IP を <IP> に入れて実行。

A. HTTP（/json/version）

curl -sD - http://<IP>:9222/json/version -o - | head -c 200
# → HTTP/1.1 200 OK & JSON に "webSocketDebuggerUrl" がある
  • webSocketDebuggerUrl の URL は /devtools/browser/...（browser ターゲット）である必要があります。/devtools/page/... ではツールが一部動きません。 (chromedevtools.github.io)

B. WebSocket（本命）

WS=$(curl -s http://<IP>:9222/json/version | jq -r .webSocketDebuggerUrl)
npx -y wscat -c "$WS"     # → connected（Ctrl+C で終了）
  • HTTP が OK でも WS が通らないと MCP は上がりません。ここで “connected” ならネットワークは準備完了。 (chromedevtools.github.io)

実務メモ：host.docker.internal:9222 で HTTP 500 が出る環境があります。これは 名前の Host ヘッダが原因で拒否される挙動だと考えられ、数値 IP の直指定なら安定します（実運用上の知見。Docker 側の転送の仕組みは公式フォーラムで解説されています）。 (Docker Community Forums)

5) Codex に chrome-devtools-mcp を登録（MCP クライアント設定）

~/.codex/config.toml（動作実績のある最小構成）：

[projects."/workspaces/codex-chrome-mcp-server"]
trust_level = "trusted"

[tools]
web_search = true

[mcp_servers.chrome-devtools]
command = "npx"
args = [
  "-y",
  "chrome-devtools-mcp@latest",
  "--browser-url=http://<IP>:9222"
]
  • --browser-url は 既存の Chrome の HTTP エンドポイント（例：http://127.0.0.1:9222）を指定する方式です。バージョンによっては CLI が --browserUrl（キャメル）を案内することもあるので、npx chrome-devtools-mcp --help の表記に合わせてください。 (GitHub)
  • より堅牢にしたければ、--wsEndpoint=ws://<IP>:9222/devtools/browser/<id> で WebSocket を直指定する方法も公式にあります。 (GitHub)

確認：

codex
/mcp
# → chrome-devtools のツール一覧が並べば成功

6) はじめての操作

うまく接続できていれば下記のようなログと共にChromeが操作されている画面が確認でいるはずです！

node ➜ /workspaces/codex-chrome-mcp-server $ codex 
╭────────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.47.0-alpha.3)              │
│                                                │
╰────────────────────────────────────────────────╯

  To get started, describe a task or try one of these commands:

  /init - create an AGENTS.md file with instructions for Codex
  /status - show current session configuration
  /approvals - choose what Codex can do without approval
  /model - choose what model and reasoning effort to use
  /review - review any changes and find issues


› chrome devtools mcpでgoogle.comからAmazonを開いて

• Updated Plan
  └ □ Open google.com in the browser

    ## Pages
    0: chrome://new-tab-page/
    1: chrome://new-tab-page/
    2: https://www.google.com/ [selected]

• Called chrome-devtools.take_snapshot({})
  └ # take_snapshot response
    ## Page content
    uid=1_0 RootWebArea "Google"
      uid=1_1 link "Googleについて"
        uid=1_2 StaticText "Googleについて"
      uid=1_3 link "ストア"
        uid=1_4 StaticText "ストア"
      uid=1_5 link "Gmail "
        uid=1_6 StaticText "Gmail"
      uid=1_7 link "画像を検索する "
        uid=1_8 StaticText "画像"
      uid=1_9 button "Google アプリ"
      uid=1_10 link "ログイン"
        uid=1_11 StaticText "ログイン"
      uid=1_12 image "Google"
      uid=1_13 combobox "検索" auto...

7) 片付け・安全運用

  • デバッグ用 Chrome は作業後に完全終了（9222 の LISTEN が無いことを確認）。
  • デバッグ中は ブラウザの中身を MCP が見られるので、機密サイトは開かない。 (GitHub)
  • プロファイルをきれいにしたいときは --user-data-dir で作ったフォルダーを削除。

付録A：ホントに困ったときの 3 点だけ切り分け

  1. HTTP：curl http://<IP>:9222/json/version が 200 & JSON（webSocketDebuggerUrl は /devtools/browser/）。 (chromedevtools.github.io)
  2. WS：wscat -c ws://<IP>:9222/devtools/browser/<id> が connected。 (chromedevtools.github.io)
  3. MCP：codex /mcp に ツール一覧が出る（Node 20.19+、CLI オプション名の表記一致）。 (GitHub)

500 など名前解決系のエラーは、数値 IP 直指定に切り替えるのが最短です。Docker Desktop の仕組み上、コンテナ →（内部ゲートウェイ）→ ホストのループバックに転送されます。 (Docker Community Forums)

付録B：オプション早見表（使い方／いつ使うか／注意点）

Chrome 起動（PowerShell）

オプション 何のため いつ使う 注意点
--remote-debugging-port=9222 CDP を開く 必須 /json/version で WS URL を取れるようになる。 (Chrome for Developers)
--user-data-dir=<dir> 既定プロファイルと分離 強く推奨 セキュリティ上の推奨。既定プロファイルでの運用は避ける。 (Chrome for Developers)
--remote-debugging-address=0.0.0.0 すべての NIC で待受 最終手段 LAN からも見えるため開発中のみ。通常は不要。
--no-first-run ほか 初回起動や拡張による揺れを防ぐ 任意 再現性向上のため。

chrome-devtools-mcp（MCP サーバ）

オプション 何のため いつ使う 注意点
--browserUrl=http://<IP>:9222 既存の Chrome に HTTP で接続 基本形 まずはこれ。数値 IP 推奨。 (GitHub)
--wsEndpoint=ws://…/devtools/browser/<id> WebSocket を直指定 Host ヘッダ/プロキシが怪しい時 --wsHeaders で認証ヘッダも付けられる。 (GitHub)
--isolated 一時プロファイルで実行 毎回クリーンに試したい時 MCP が Chrome を起動するモード向け。 (GitHub)
--headless UI を出さずに実行 CI/無人運用 同上（既存接続では影響なし）。 (GitHub)
--channel / --executablePath 起動する Chrome を選ぶ MCP が Chrome を起動する時 既存接続では基本不要。 (GitHub)
--logFile + DEBUG='*' 詳細ログを保存 トラブル時 バグ報告・自己診断に便利。 (GitHub)

DevContainer / Docker

設定 何のため いつ使う 注意点
--add-host=host.docker.internal:host-gateway コンテナ→ホスト到達の安定化 推奨 /etc/hosts に IPv4 が入る。 (Docker Documentation)
Rebuild 設定反映 変更ごと 反映忘れに注意。 (Visual Studio Code)

WSL（任意だが便利）

設定 何のため いつ使う 注意点
.wslconfig: [wsl2] networkingMode=mirrored Windows のネットワークを WSL に“鏡写し” VPN/プロキシ併用 設定後は wsl --shutdown。 (Microsoft Learn)

参考・出典

  • chrome-devtools-mcp：要件（Node 20.19+）、構成・オプション、Tool 一覧、既存 Chrome への接続方法（--browserUrl/--wsEndpoint）など。 (GitHub)
  • DevTools Protocol：/json/version と browser エンドポイント説明。 (chromedevtools.github.io)
  • Remote debugging / local server（Chrome 公式）：ローカルサーバや既存ブラウザへの接続ガイド。 (Chrome for Developers)
  • Docker Desktop Networking：host.docker.internal や内部転送の仕組み。 (Docker Documentation)
  • VS Code Dev Containers：devcontainer.json の基本と再ビルド。 (Visual Studio Code)
  • WSL ネットワーク（mirrored）：.wslconfig の networkingMode=mirrored。 (Microsoft Learn)
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?