Playwright MCPで始めるブラウザ自動化｜環境別セットアップガイド

1 はじめに
2 この記事で伝えたいこと
3 Playwright MCPの基本
- 3.1 Playwright MCPとは
- 3.2 主な機能
4 3つのセットアップ方式
- 4.1 方式の比較表
- 4.2 環境別推奨マトリクス
5 方法1: npx版（開発環境推奨）
6 方法2: Docker Compose版（常駐型・開発環境向け）
7 方法3: Docker直接実行版（都度起動型・本番環境推奨）
8 コラム：DevContainerでの選択
9 実際の使い方
- 9.1 Claude Codeでの基本操作
10 トラブルシューティング
11 まとめ
12 参考リンク

はじめに

ども！Claude Codeを執筆に贅沢活用している龍ちゃんです。やっとPlaywright MCPを触る機会ができました。話題になってただけあって、めちゃくちゃ便利ですね。

前回の記事「Claude Code SkillでHTML図解を自動生成！時短テクニック」で、Claude CodeにHTMLで図解を作ってもらう方法を紹介したんですが、スクリーンショットの手間が面倒じゃないですか。ブラウザで開いて、サイズ合わせて…って。しかも僕、DevContainer環境でブログ書いてるんで、いい感じに開けないんですよね。

そこでPlaywright MCPを使ったら、さくっと実装してくれたんです。これは感動しました。

Playwright MCPは、Microsoft公式のModel Context Protocol (MCP)サーバーで、Claude CodeからPlaywrightのブラウザ自動化機能を直接呼び出せます。スクリーンショット取得はもちろん、ページ遷移、フォーム入力、要素のクリックなど、22個ものツールが使えます。

ただ、セットアップ方法が「npx版」「Docker Compose版」「Docker直接実行版」と3種類あって、正直どれ選べばいいかわかんないですよね。

僕自身、Node.jsが使える環境とPythonしか使えない環境でそれぞれ開発してて、「どっちにも適用したいけど、どうしよう？」って悩んだんです。そこで今回、npx版とDocker版それぞれのセットアップを検証しました。

この記事では、環境別に最適なPlaywright MCPのセットアップ方法を紹介します。開発環境、本番環境、DevContainer環境など、それぞれのケースでどの方式を選べばいいかを明確にしていきます。

すべての設定ファイルと詳細なREADMEは、GitHubリポジトリで公開しています（npx版、Docker Compose版、Docker直接実行版すべて含む）。

この記事で伝えたいこと

環境に合わせて最適なPlaywright MCPのセットアップ方法を選べるようになります。

この記事で扱う内容:

3つのセットアップ方式（npx版、Docker Compose版、Docker直接実行版）の比較
環境別の推奨方法（開発環境、本番環境、CI/CD、DevContainer）
すぐ試せるコード例（コピペ可能な設定ファイル）
DevContainerでの2つの選択肢（npx vs Docker）

Playwright MCPの基本

Playwright MCPとは

Playwright MCPは、Microsoft Playwrightチームが公式に提供するMCPです。Claude CodeからPlaywrightのブラウザ自動化機能を直接呼び出せます。

パッケージ情報:

npm: @playwright/mcp
バージョン: 0.0.47（2025年11月14日公開）
ライセンス: Apache-2.0
メンテナー: Microsoft Playwright公式チーム

主な機能

Playwright MCPはコアツール20個に加え、タブ管理とブラウザインストールの計22個が標準で利用可能です。さらに、--capsフラグでopt-inすることで、座標ベース操作、PDF生成、テストアサーション、トレーシングなど追加11個（合計33個）のツールが使えます。

本記事では、コアツールのうち以下の7個を実際に検証しました：

ツール	機能	用途
`browser_navigate`	ページ遷移	URLを開く
`browser_snapshot`	ページ構造取得	DOM情報を取得
`browser_take_screenshot`	スクリーンショット	PNG画像を保存
`browser_console_messages`	コンソールログ取得	デバッグ情報の確認
`browser_evaluate`	JavaScript実行	カスタムスクリプト実行
`browser_install`	ブラウザインストール	Chromiumのセットアップ

残り15個のツール（要素操作、高度な機能）は未検証ですが、公式ドキュメントによると以下のような機能があります：

要素操作: browser_click, browser_type, browser_fill_form
タブ管理: browser_tabs, browser_close
ファイル操作: browser_file_upload

3つのセットアップ方式

方式の比較表

項目	npx版	Docker Compose版	Docker直接実行版
Node.js必須	✅ 必要	❌ 不要	❌ 不要
Docker必須	❌ 不要	✅ 必要	✅ 必要
セットアップ時間	5分	5分（初回）、10秒（2回目以降）	中程度
設定ファイル	`.mcp.json`のみ	`compose.yml` + `.mcp.json`	`.mcp.json`のみ
ディスク使用量	約300MB	約1GB	約1GB
メモリ消費	低（数百MB）	中〜高（約1GB、常駐）	低（使用時のみ）
起動速度	1-2秒	1-2秒	中程度

環境別推奨マトリクス

ユースケース	推奨方式	理由
個人開発（単一プロジェクト）	npx版 ⭐⭐⭐⭐⭐	セットアップ簡単、高速、安定
チーム開発（開発環境）	npx版 ⭐⭐⭐⭐⭐	`.mcp.json`で共有可能
複数プロジェクト共有（開発）	Docker Compose版 ⭐⭐⭐⭐	常駐型で複数プロジェクトから利用
本番環境	Docker直接実行版 ⭐⭐⭐⭐⭐	公式推奨、セキュア、独立実行
CI/CD	Docker直接実行版 ⭐⭐⭐⭐⭐	クリーン環境、再現性、並列実行
DevContainer環境	npx版 ⭐⭐⭐⭐⭐	stdio接続、Node.js標準搭載

方法1: npx版（開発環境推奨）

設定ファイル（コピペ可能）

プロジェクトルートに .mcp.json を作成します：

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--isolated",
        "--browser",
        "chromium",
        "--no-sandbox"
      ]
    }
  }
}

重要なフラグ:

@latest: 常に最新版を使用（本番環境では@0.0.47等のバージョン固定を推奨）
--headless: DevContainer/Docker環境で必須（GUI表示不可能な環境）
--isolated: プロファイルロック問題を回避（必須フラグ）
--browser chromium: ブラウザを明示的に指定
--no-sandbox: DevContainer/Docker環境で必須

⚠️ セキュリティ警告: --no-sandboxフラグはChromiumのサンドボックス保護を無効化します。DevContainer/Docker環境では必須ですが、本番環境での使用は慎重に検討してください。

セットアップ手順（5分）

Step 1: 上記の.mcp.jsonをプロジェクトルートに作成

Step 2: VSCodeをリロード

Cmd/Ctrl + Shift + P → “Developer: Reload Window”

Step 3: Chromiumをインストール

npx playwright install chromium

ダウンロードサイズ: 約174MB
所要時間: 約30秒

Step 4: 動作確認

Claude Codeで以下のように依頼します：

Playwright MCPを使用して、https://example.com を開いてページタイトルを取得してください

期待される結果:

ページURL: https://example.com
ページタイトル: “Example Domain”
エラーなし

メリット・デメリット

✅ メリット（開発環境）:

インストール不要 – npx経由で即座に実行
公式サポート – Microsoft公式チームがメンテナンス
最新版自動取得 – @latestで常に最新
高速・軽量 – 1-2秒で起動（開発環境で検証済み）
チーム共有簡単 – .mcp.jsonをGit管理
構造化アプローチ – アクセシビリティツリー使用

❌ デメリット・制約:

開発環境向け – 本番環境での使用は未検証
初回起動遅い – パッケージダウンロード（数秒〜数十秒）
ネットワーク依存 – インターネット接続必要（初回/@latest使用時）
Node.js必須 – Node.js v20以上が必要
キャッシュ管理 – npm cacheに約300MB消費

推奨ケース

✅ npx版が最適:

個人開発（単一プロジェクト）
チーム開発（.mcp.json共有）
DevContainer環境
頻繁な使用（開発中）
プロトタイピング・検証

⚠️ npx版を本番環境で使用する場合の推奨事項:

本記事では主に開発環境での使用を検証していますが、本番環境で使用する場合は以下の対策を推奨します：

バージョン固定: @latestではなく@0.0.47等の具体的なバージョンを指定
十分な検証: 負荷テスト・セキュリティ検証を実施
監視体制: エラーハンドリング・監視体制を構築
障害対策: ネットワーク障害時の挙動を確認

より安全な本番環境運用には、Docker直接実行版の検討もご検討ください（セキュリティ重視、クリーン環境）。

方法2: Docker Compose版（常駐型・開発環境向け）

compose.yml（コピペ可能）

プロジェクトルートに compose.yml を作成します：

services:
  playwright-mcp:
    image: mcr.microsoft.com/playwright:v1.49.1-noble
    container_name: playwright-mcp-server
    ports:
      - "8931:8931"
    environment:
      - PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
      - PLAYWRIGHT_CHROMIUM_ARGS=--no-sandbox --disable-setuid-sandbox
    command: >
      sh -c "
        npx playwright install chrome &&
        npm install -g @playwright/mcp@latest &&
        npx @playwright/mcp@latest --port 8931 --headless --isolated --no-sandbox
      "
    restart: unless-stopped
    networks:
      - mcp-network

networks:
  mcp-network:
    name: mcp-network
    driver: bridge

.mcp.json（コピペ可能）

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "playwright-mcp-server",
        "node",
        "/root/.npm/_npx/9833c18b2d85bc59/node_modules/.bin/mcp-server-playwright",
        "--isolated",
        "--no-sandbox"
      ]
    }
  }
}

注意: npxのパス（/root/.npm/_npx/...）は環境により異なる場合があります。

パスの確認方法:

docker exec -it playwright-mcp-server bash
find /root/.npm/_npx -name "mcp-server-playwright"

パスが異なる場合は、.mcp.jsonの該当箇所を更新してください。

セットアップ手順

Step 1: 上記のcompose.ymlをプロジェクトルートに作成

Step 2: サーバー起動

docker compose up -d

初回: 約5分（イメージ743MB + Chrome 112MB）
2回目以降: 約10秒

Step 3: 上記の.mcp.jsonを作成（npxパスを確認）

Step 4: VSCodeをリロード

メリット・デメリット

✅ メリット:

複数プロジェクト共有 – 常駐型で複数から利用可能
環境分離 – Dockerコンテナで独立
自動再起動 – restart: unless-stopped
管理が簡単 – Docker Composeで一元管理
stdio接続 – docker exec経由で安定した通信

❌ デメリット:

初回起動時間 – 約5分（イメージ743MB + Chrome 112MB）
リソース常時消費 – メモリ・CPU常駐（約1GB）
npxパス依存 – パスが環境により異なる可能性
Docker知識必要 – Docker/Docker Composeの理解が必要

推奨ケース

✅ Docker Compose版が適している場合:

複数のプロジェクトで共有したい
開発環境での頻繁な使用
チーム全体で統一環境を使用したい
リソースを常時確保できる環境がある

❌ npx版が適している場合:

単一プロジェクトでのみ使用
リソース消費を最小限に抑えたい
Docker環境を構築したくない
安定したパフォーマンスが必要

方法3: Docker直接実行版（都度起動型・本番環境推奨）

.mcp.json（コピペ可能）

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "--pull=always",
        "mcr.microsoft.com/playwright/mcp",
        "--isolated"
      ]
    }
  }
}

特徴とメリット

特徴:

公式イメージ: mcr.microsoft.com/playwright/mcp
実行方式: docker run --rm（終了後自動削除）
セッション毎に新しいコンテナ: 完全に独立
公式ドキュメントで紹介: セキュリティ重視の場合に適した方式

✅ メリット:

最もセキュア – セッション毎に独立
リソース効率的 – 使用時のみ起動
常に最新 – --pull=alwaysで最新イメージ
クリーン – --rmで自動削除
本番環境向け設計

推奨ケース

✅ Docker直接実行版が適している場合:

本番環境 – セキュリティ重視
CI/CD環境 – クリーンな環境、再現性
各実行が独立が必要 – テストの独立性
リソース効率重視 – 使用時のみリソース消費
常に最新版を使用 – 自動更新が必要

❌ 他の方式が適している場合:

npx版 – Node.js環境があり、高速起動が必要（開発環境）
Docker Compose版 – 複数プロジェクトで共有、常駐型が必要（開発環境）

コラム：DevContainerでの選択

DevContainer環境でPlaywright MCPを使う場合、2つの選択肢があります。僕自身、最初はどちらを選べばいいか迷ったんですが、実際に両方試してみて分かったことをシェアします。

選択肢1: npx版をコンテナ内に収める

設定例（.mcp.json）:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--isolated",
        "--no-sandbox"
      ]
    }
  }
}

✅ メリット:

シンプル – DevContainerにはNode.js標準搭載
高速 – ネットワーク経由不要、stdio接続
設定が簡単 – .mcp.jsonのみ

❌ デメリット:

Node.js必須 – DevContainerにNode.jsが必要
コンテナサイズ増加 – npm cache約300MB

選択肢2: Docker版をホストで動かす

設定例（Docker Compose版の場合）:

DevContainerのdevcontainer.jsonでホストDockerソケットを共有：

{
  "mounts": [
    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
  ]
}

.mcp.jsonは「方法2: Docker Compose版」と同じ。

✅ メリット:

Node.js不要 – DevContainerにNode.jsが不要
リソース分離 – ホスト側でブラウザ実行

❌ デメリット:

Docker socket共有が必要 – セキュリティ考慮が必要
設定が複雑 – devcontainer.jsonの編集が必要
ネットワーク経由 – やや遅延が発生する可能性

どちらを選ぶか

僕の推奨: npx版をコンテナ内に収める

理由は以下の3つです：

DevContainerにはNode.js標準搭載
わざわざDockerソケット共有の設定をする必要がない
高速で安定
stdio接続なので、ネットワーク経由の遅延がない
シンプル
.mcp.jsonだけで完結

Docker版が必要なケース:

Node.jsを使わないプロジェクト（Python専用など）
リソースを完全に分離したい
複数のDevContainerプロジェクトで共有したい

実際の使い方

Claude Codeでの基本操作

セットアップが完了したら、Claude Codeで以下のように依頼するだけで使えます：

例1: ページを開いてスクリーンショット

Playwright MCPを使って、https://playwright.dev を開いて、スクリーンショットを撮影してください

例2: ページタイトルを取得

Playwright MCPで https://example.com のページタイトルを取得してください

パフォーマンス・動作確認データ（参考）

動作確認（npx版、開発環境で検証）:

操作	時間	結果
ブラウザ起動（初回）	1-2秒	✅
ブラウザ起動（2回目以降）	< 1秒	✅
example.com ナビゲーション	< 1秒	✅
playwright.dev ナビゲーション	< 2秒	✅
スクリーンショット取得	< 1秒	✅

3つの方式のパフォーマンス比較:

操作	npx版	Docker Compose版
ブラウザ起動	1-2秒	1-2秒
ページアクセス	< 1秒	27-94秒（ばらつき大）
スクリーンショット	< 1秒	< 1秒
初回セットアップ	約30秒	約5分

結論: 実用上は大きな差はありませんが、npx版の方が安定している印象です。Docker Compose版はページアクセスにばらつきがあるので、開発環境で頻繁に使うならnpx版がおすすめです。

驚くほど高速でした。 特にnpx版は、開発環境での使用であれば非常に安定しています。

トラブルシューティング

問題1: プロファイルロックエラー

エラーメッセージ:

Error: Browser is already in use for /home/node/.cache/ms-playwright/mcp-chrome-*
use --isolated to run multiple instances of the same browser

解決策:

.mcp.jsonに--isolatedフラグを追加
VSCodeをリロード

予防策: 最初から--isolatedを含める（強く推奨）

問題2: MCPサーバーが認識されない

解決策:

.mcp.jsonの構文確認（JSONバリデーター使用）
VSCodeをリロード
Claude CodeのOutputパネルでエラーログ確認

問題3: Chromiumが起動しない

解決策:

npx playwright install chromium

Chromiumがインストールされていない場合は、上記コマンドで手動インストールしてください。

問題4: Docker Compose版でnpxパスが見つからない

解決策:

docker exec -it playwright-mcp-server bash
find /root/.npm/_npx -name "mcp-server-playwright"

パスを確認して、.mcp.jsonを更新してください。

まとめ

今回は、Playwright MCPの環境別セットアップ方法を紹介しました。

環境別の選択ガイド

開発環境（個人・チーム）: npx版 ⭐⭐⭐⭐⭐

セットアップ簡単（5分）
.mcp.jsonだけで完結
高速・安定

開発環境（複数プロジェクト）: Docker Compose版 ⭐⭐⭐⭐

常駐型で複数から利用
環境分離

本番環境/CI/CD: Docker直接実行版 ⭐⭐⭐⭐⭐

公式推奨
セキュア
クリーン環境

DevContainer環境: npx版 ⭐⭐⭐⭐⭐

Node.js標準搭載
stdio接続で高速

この記事で実現できたこと

✅ 環境に合わせた最適なセットアップ方法の選択
✅ コピペで試せる設定ファイル
✅ DevContainerでの選択肢（npx vs Docker）
✅ トラブルシューティング

より詳しく知りたい方へ: すべての設定ファイルと詳細なREADMEは、GitHubリポジトリで公開しています（npx版、Docker Compose版、Docker直接実行版すべて含む）。

次のステップ

前回の記事「Claude Code SkillでHTML図解を自動生成！時短テクニック」で紹介したHTML図解の作成と、今回のPlaywright MCPセットアップを組み合わせることで、HTML→PNG変換の完全なワークフローが実現できます。

次回は、このHTML→PNG変換の詳細について解説する予定です。Playwright MCPを使った自動スクリーンショット取得、画像最適化、ブログへの埋め込みまでの一連の流れを紹介します。

皆さんも、ぜひPlaywright MCPでブラウザ自動化にチャレンジしてみてください！質問や感想は、コメント欄でお待ちしております。

参考リンク

公式ドキュメント

前提記事

Claude Code SkillでHTML図解を自動生成！時短テクニック
- HTML図解の自動生成方法
- Tailwind CSS + Material Iconsの活用
- PNG変換の基本

GitHubリポジトリ

playwright-mcp-sample
- 3つのセットアップ方法の完全なサンプルコード
- DevContainer対応
- すべて動作検証済み
- 詳細なREADME（日本語）
- MITライセンス

次に読むべき記事

HTML→PNG変換の詳細（次回予定）
Playwright MCPを使った自動スクリーンショット
画像最適化のベストプラクティス
ブログへの埋め込みワークフロー

最後まで読んでいただき、ありがとうございました！

この記事が役に立ったら、ぜひSNSでシェアしてください。質問やフィードバックは、@RyuReina_Tech や @SIOSTechLab でお待ちしています！

ご覧いただきありがとうございます！この投稿はお役に立ちましたか？

役に立った役に立たなかった

0人がこの投稿は役に立ったと言っています。

はじめに

この記事で伝えたいこと

Playwright MCPの基本

Playwright MCPとは

主な機能

3つのセットアップ方式

方式の比較表

環境別推奨マトリクス

方法1: npx版（開発環境推奨）

設定ファイル（コピペ可能）

セットアップ手順（5分）

メリット・デメリット

推奨ケース

方法2: Docker Compose版（常駐型・開発環境向け）

compose.yml（コピペ可能）

.mcp.json（コピペ可能）

セットアップ手順

メリット・デメリット

推奨ケース

方法3: Docker直接実行版（都度起動型・本番環境推奨）

.mcp.json（コピペ可能）

特徴とメリット

推奨ケース

コラム：DevContainerでの選択

選択肢1: npx版をコンテナ内に収める

選択肢2: Docker版をホストで動かす

どちらを選ぶか

実際の使い方

Claude Codeでの基本操作

トラブルシューティング

問題1: プロファイルロックエラー

問題2: MCPサーバーが認識されない

問題3: Chromiumが起動しない

問題4: Docker Compose版でnpxパスが見つからない

まとめ

環境別の選択ガイド

開発環境（個人・チーム）: npx版 ⭐⭐⭐⭐⭐

開発環境（複数プロジェクト）: Docker Compose版 ⭐⭐⭐⭐

本番環境/CI/CD: Docker直接実行版 ⭐⭐⭐⭐⭐

DevContainer環境: npx版 ⭐⭐⭐⭐⭐

この記事で実現できたこと

次のステップ

参考リンク

公式ドキュメント

前提記事

GitHubリポジトリ

次に読むべき記事

コメントを残す コメントをキャンセル

コメントを残すコメントをキャンセル