Playwright MCP の Claude Code セットアップ手順ガイド

1 行でインストール

Claude Code で Playwright MCP を使うには、claude mcp add playwright npx @playwright/mcp@latest を実行して claude を起動し、/mcp で playwright が接続済みになっていることを確認します。これで Claude は Microsoft 公式の Playwright MCP サーバーを通じて、本物のブラウザを開き、クリック、入力、ページの読み取り、スクリーンショット撮影ができるようになります。

このコマンドは Playwright MCP の README にそのまま載っているものです。このガイドの残りでは、動いた直後に直面する選択肢を扱います。どのスコープに入れるか、ヘッドありかヘッドレスか、永続プロファイルか分離プロファイルか、追加機能、そしてブラウザが起動しないときの対処です。

Playwright MCP は何をするのか

Playwright MCP は、browser_navigate、browser_click、browser_type、browser_fill_form、browser_snapshot、browser_take_screenshot などの MCP ツールとしてブラウザ自動化を提供します。モデルにスクリーンショットを送る代わりに、アクセシビリティスナップショットを返します。これはページ要素の構造化されたツリーで、Claude がクリックや入力に使える参照が付いています。そのため高速で、画像ベースの方法よりコストが低く、どの要素を操作するかが決定的です。

Claude Code での典型的な使い方：

• 作ったばかりの機能がブラウザで本当に動くか確かめる。
• チケットに書かれた UI バグを手順どおりに再現する。
• サイトを探索してから Playwright テストを書く。
• フォームに入力したり、JavaScript が必要なページからデータを取り出したりする。

前提条件

• Node.js 18 以上（README に明記された要件）。node --version で確認します。
• インストール済みでサインインした Claude Code。
• Playwright が操作できるブラウザ。--browser で chrome、firefox、webkit、msedge から選べます。

ステップ 1：サーバーを追加する

最速：local スコープ

claude mcp add playwright npx @playwright/mcp@latest

デフォルトの local スコープに保存され、現在のプロジェクトで自分だけが使えます。

すべてのプロジェクトで使う：user スコープ

claude mcp add --scope user playwright -- npx @playwright/mcp@latest

Playwright MCP 自体にオプションを渡すときは、起動コマンドを必ず -- の後ろに置きます。こうすると Claude Code が --headless などを自分のオプションとして読み取ることがありません。

チームで共有：project スコープ

claude mcp add --scope project playwright -- npx @playwright/mcp@latest

プロジェクトルートにコミット可能な .mcp.json が書き込まれます：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

チームメイトはリポジトリで初めて claude を起動したときにサーバーの承認を求められます。スコープと承認の全体像は Claude Code MCP ガイドを参照してください。

ステップ 2：接続を確認する

claude mcp list

playwright に ✔ Connected と表示されていれば OK です。セッション内の /mcp でも同じ状態とツール一覧が見られます。✘ Failed to connect と出たら、下のトラブルシューティング表に進んでください。

ステップ 3：最初のプロンプトを実行する

初回はツール名をはっきり指定しましょう。そうしないと、Claude がシェル経由で Playwright スクリプトを書いて実行しようとすることがあります：

Use the playwright MCP to open https://mcp.so, search for "github",
and tell me the first three results.

ブラウザウィンドウが開き（サーバーはデフォルトでヘッドありモード）、Claude が操作する様子を見られます。許可していない限り、Claude Code は新しいツールを使う前に毎回許可を求めます。

便利なオプション

オプションはすべて起動コマンドのパッケージ名の後ろ、または .mcp.json の args 配列に書きます。どのオプションにも対応する PLAYWRIGHT_MCP_* 環境変数があります。

ヘッドレスで分離された Firefox の設定はこうなります：

claude mcp add playwright -- npx @playwright/mcp@latest \
  --headless --browser firefox --isolated

.mcp.json でも同じように書けます。こちらは PDF と vision のツールも有効にしています：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--isolated",
        "--caps=vision,pdf"
      ]
    }
  }
}

ケイパビリティの詳細

• vision は座標ベースのマウスツールを追加します。canvas アプリや、アクセシビリティツリーにうまく現れない要素に向いています。
• pdf は browser_pdf_save を追加します。
• devtools はトレース、録画、要素のハイライトを追加します。

README にはネットワークのモック、Cookie とストレージ、設定、テストアサーションといったオプトインのツール群も記載されています。必要なものだけを有効にしましょう。ツールが 1 つ増えるたびに、Claude が検討する定義も 1 つ増えます。

プロファイルとログイン

Playwright MCP はデフォルトで永続プロファイルを使うため、ログイン状態はセッションをまたいで残ります。プロファイルはプロジェクトごとに保存されます：

• macOS：~/Library/Caches/ms-playwright/mcp- の後にチャンネル名とワークスペースのハッシュ
• Linux：~/.cache/ms-playwright/mcp- の後にチャンネル名とワークスペースのハッシュ
• Windows：%USERPROFILE%\AppData\Local\ms-playwright\mcp- の後にチャンネル名とワークスペースのハッシュ

そのフォルダを削除すれば、すべてのログインが解除されます。永続プロファイルは同時に 1 つのブラウザしか使えないため、同じプロジェクトで 2 つのターミナルから Claude Code を動かす場合は、2 つ目に --isolated か別の --user-data-dir を指定してください。

実際のアカウントが必要なタスクでは、--extension モードで別のブラウザではなく自分の Chrome や Edge のタブに接続できます。これは慎重に使ってください。Claude がブラウザでできることは、すべてあなたとして行われます。ログイン済みの本番アカウントをエージェントに操作させる前に、MCP セキュリティのベストプラクティスを読んでおきましょう。

うまくいくプロンプト例

• 「Use playwright mcp to open http://localhost:3000、テスト用メールアドレスでサインアップし、ウェルカムページがコンソールエラーなしで表示されるか教えて。」
• 「料金ページを開き、1280x720 と iPhone のビューポートでそれぞれスクリーンショットを撮って、レイアウトの違いを挙げて。」
• 「このバグ報告をブラウザで手順どおりに再現し、最初に失敗したステップで止めて。」
• 「チェックアウトの流れを探索してから、正常系をカバーする Playwright テストを tests/checkout.spec.ts に書いて。」
• 「問い合わせフォームにサンプルデータを入力して送信し、ネットワークの応答を報告して。」

トラブルシューティング

サーバーがどのツールを公開し、何を返しているかを正確に見たいときは、MCP Inspector に接続してみてください。

Docker で動かす場合

README ではコンテナイメージも提供されています。現在はヘッドレスの Chromium のみ対応です：

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

すでにゲートウェイ経由でサーバーをまとめているなら、Docker MCP Gateway のセットアップを参照してください。

Playwright MCP と Playwright CLI

Playwright チームは、コーディングエージェントでは Playwright CLI と skills のほうがうまくいく場合があると率直に述べています。短い CLI 呼び出しなら、大きなツール定義やアクセシビリティツリーをコンテキストに読み込まずに済むからです。一方、Claude がブラウザを開いたままページ構造を一歩ずつ推論する必要がある場面、たとえば探索的テストや自己修復テストでは、MCP のほうが適しています。Claude Code ではツール検索が使わないツール定義をもともとコンテキストから外してくれるので、対話的なブラウザ作業なら MCP をデフォルトにして問題ありません。長時間・大量の実行では CLI を検討してください。

もっとシンプルなヘッドレスのスクレイパーで足りるなら Puppeteer MCP サーバーという選択肢もありますが、Playwright MCP は Microsoft 公式のクロスブラウザ対応の選択肢です。

次のステップ

Playwright MCP が動いたら、作業のループを閉じるサーバーと組み合わせましょう。課題管理ツールでバグ報告を読む、あるいは GitHub MCP サーバーで修正と新しいテストを含む PR を作る、といった使い方です。ほかのサーバーは MCP サーバーディレクトリで探すか、追加したものすべてを管理するために Claude Code MCP ガイドの全文を読んでみてください。