Playwright MCPの設定はどこに書く? Claude Codeでの導入手順

Playwright MCPは、MicrosoftのPlaywrightをMCP(Model Context Protocol)経由でAIから操作できるようにするサーバーです。テストコードは書きません。ブラウザのクリック・入力・スクリーンショット取得・ページ内容の解析を、Claude Codeへの自然文の指示だけで実行できます。

設定はclaude mcp addのargs、PLAYWRIGHT_MCP_で始まる環境変数、--configで渡すJSONファイルの3か所に書けます。

本記事はPlaywright MCP単体の導入と使いどころに絞ります。MCPプロトコル自体の仕組みはMCPとは、Claude CodeでのMCP設定全般(スコープ・.mcp.json・OAuth認証)はClaude Code MCP設定ガイドを参照してください。既存のE2Eスイートをhookで自動実行し失敗をClaude Codeに直させる運用はClaude CodeとPlaywrightでE2Eテストを回す手順にまとめています。canvasゲームの画面確認に使う例はClaude CodeでPhaserゲームを作る手順にあります。

Playwright MCPとは — アクセシビリティツリーで動くブラウザ操作

Playwright MCPは、パッケージ名@playwright/mcpとしてnpmで公開されているMicrosoft公式のMCPサーバーです。ライセンスはApache-2.0。内部でPlaywright本体(playwright / playwright-core)に依存しています。

このサーバーの設計上の特徴は、スクリーンショットではなくPlaywrightのアクセシビリティツリーを使う点です。アクセシビリティツリーとは、ページ内の要素を「ボタン」「リンク」「見出し」といった役割と名前の構造データとして表現したものです。画像を解析するビジョンモデルなしに、テキストベースの構造情報だけで要素を特定できるため、クリックやフォーム入力の対象を取り違えにくくなります。スクリーンショット自体もbrowser_take_screenshotツールで取得できます。ただしREADMEの説明どおり、画面の操作はスクリーンショットではなくbrowser_snapshotの結果をもとに行う設計です。

動作にはNode.js 18以上が必要です。Claude Codeに限らず、VS Code・Cursor・Windsurf・Claude Desktop・Goose・Junieなど、MCPクライアントであれば基本的にどこからでも同じサーバーを使い回せます。

Claude CodeにPlaywright MCPを追加する

追加はローカルstdioサーバーとしてclaude mcp addの1行で完了します。オプションとサーバー名の後に--(ダブルダッシュ)を置き、その後ろが実際に起動するコマンドです。

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

@latestタグを使うと、起動のたびに最新版のPlaywright MCPがnpx経由で取得されます。バージョンを固定したい場合は@playwright/mcp@0.0.83のように具体的なバージョン番号を指定します(npmのlatestタグは0.0.83を指しています)。追加後はclaude mcp listで接続状態を確認するか、セッション内で/mcpを実行するとツール一覧が表示されます。

スコープで接続までの道のりが変わる

claude mcp add --helpにあるとおり、--scopeを付けなければ既定のlocalで追加されます。チームで同じ設定を共有したいときは--scope projectを付け、リポジトリの.mcp.jsonに書き出します。この場合は承認の1段が増えます。

Claude Code v2.1.287で、空のディレクトリを使って実際に確認した出力です。

claude mcp add --scope project playwright -- npx @playwright/mcp@latest --isolated --headless
# Added stdio MCP server playwright with command: npx @playwright/mcp@latest --isolated --headless to project config
# File modified: ./.mcp.json
 
claude mcp get playwright
# playwright:
#   Scope: Project config (shared via .mcp.json)
#   Status: ⏸ Pending approval (run `claude` to approve)
#   Type: stdio
#   Command: npx
#   Args: @playwright/mcp@latest --isolated --headless

書き出された.mcp.jsonは次の内容でした。--以降のコマンドがcommandとargsに分かれ、typeはstdio、envは空のオブジェクトになります。

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

この形を覚えておくと、後述するオプションを.mcp.jsonのargs配列へ直接足す編集もそのまま行えます。

MCP経由で使うか、Playwright CLI+SKILLSで使うか

Claude CodeのようなコーディングエージェントにPlaywrightを組み込む方法は、MCPサーバーだけではありません。同じリポジトリのREADMEは、コーディングエージェント向けにCLIベースのツール(Playwright CLI+SKILLS)を別に案内しており、用途によってはそちらが向くと説明しています。

MCPサーバーのまま使うなら、トークンの重さには起動オプションで対処できます。後述の--snapshot-modeと--mobileがその例です。Anthropic公式のスキルでPythonスクリプトを書かせる方式はwebapp-testingスキルの解説にあります。

主要なCLIオプション

Playwright MCPはnpx @playwright/mcp@latestの後ろに渡す起動時オプションで、ブラウザの種類や実行環境を細かく制御できます。オプションの置き場所の使い分けは後述します。

複数のオプションを組み合わせる例です。

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

複数の値を取るオプションは区切り文字が揃っていません。READMEの記述では、--capsと--allowed-hostsはカンマ区切り、--allowed-originsと--blocked-originsはセミコロン区切りです。--allowed-originsにカンマ区切りで書くと、意図したオリジンの絞り込みにならないおそれがあります。

--idle-timeoutの既定はヘッドレスが1時間、ヘッドありは閉じません(0で無効)。ヘッドありで開きっぱなしのウィンドウが気になる場合は、この値を設定するという手があります。Docker経由でも実行できますが、現行のDockerイメージが対応するのはヘッドレスのChromiumだけです。

Playwright MCPの設定はどこに書くか

設定の置き場所は3通りあります。主な起動オプションはどこに書いても指定できますが、launchOptionsやcontextOptionsのような細かい指定はJSON設定ファイルでしか書けません。迷ったら、まずargsに足し、項目が増えたらJSON設定ファイルへ移すと整理しやすくなります。

環境変数は、.mcp.jsonのenvに書くかclaude mcp addの--envで渡せます。オプション名のハイフンはアンダースコアになります(--user-data-dirはPLAYWRIGHT_MCP_USER_DATA_DIR)。

--envをサーバー名の直前に置くと、サーバー名がKEY=valueとして読まれてしまいます。間に別のオプションを挟むか、.mcp.jsonのenvに書いてください。

例外もあります。--no-webmcpに対応するのはPLAYWRIGHT_MCP_WEBMCP=falseで、接頭辞の後ろが単純なオプション名の大文字化にならないため、READMEの表で個別に確かめてください。

JSON設定ファイルのbrowserには、READMEのスキーマで次の項目があります。

claude mcp add playwright -- npx @playwright/mcp@latest --config ./playwright-mcp.json

{
  "browser": {
    "browserName": "chromium",
    "isolated": true,
    "launchOptions": { "headless": true },
    "contextOptions": { "viewport": { "width": 1280, "height": 720 } }
  }
}

--caps configを渡すとbrowser_get_configツールが現れ、CLIオプション・環境変数・設定ファイルをまとめた最終的な設定値を返します。READMEのオプション表はconfigを挙げていないので、後述のとおり手元でツールが現れるか確かめてください。

プロファイルの使い分け — 永続 / 分離 / ブラウザ拡張

Playwright MCPはログイン状態やCookieの持ち回り方を3通りから選べます。デフォルトは永続プロファイルです。

永続プロファイルの保存先はOSごとに異なり(macOSは~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash})、{workspace-hash}はMCPクライアントの作業ディレクトリから自動生成されるため、プロジェクトごとに別プロファイルになります。ただし1つの永続プロファイルは同時に1つのブラウザインスタンスからしか使えません。同じワークスペースで複数のMCPクライアントを並行稼働させたい場合は、--isolatedを付けるか--user-data-dirで別ディレクトリを指定して衝突を避けます。

READMEの記述は、この点で食い違って見えます。--user-data-dirの説明には「未指定なら一時ディレクトリを作る」とある一方、プロファイルの節は「既定は永続プロファイル」で保存先を上記のパスとしています。保存先を確実に自分で決めたいなら、既定に任せず--user-data-dirを明示するほうが読み違いを避けられます。

使えるツール — コア自動化から画面外の追加機能まで

Playwright MCPが公開するツールは、既定で有効な「コア自動化」群と、--capsで明示的に有効化する追加群に分かれます。READMEのツール一覧では、既定で有効な群がコア自動化24本とタブ管理(browser_tabs)1本に分かれています。主なものは次のとおりです。

--capsで有効化する追加ツールは目的別に分かれています。

有効化は起動オプションの--capsにカンマ区切りで渡します。

claude mcp add playwright -- npx @playwright/mcp@latest --caps vision,pdf

注意したいのは、READMEの中で--capsの扱いが2か所で食い違っている点です。オプション表の--capsは取り得る値をvision, pdf, devtoolsの3つだけにしています。一方でツール一覧はconfig・network・storage・testingも「opt-in via --caps」と案内しています。READMEの表が値として挙げているのはvision・pdf・devtoolsで、残る4つは、渡したときにツールが現れるかを自分の環境で試してから前提にしてください。

セキュリティ上の注意

READMEは「Playwright MCPはセキュリティ境界ではない」と明記しています。実際に注意が必要な点が4つあります。

最も強い権限を持つのがbrowser_run_code_unsafeツールです。READMEの説明は「任意のJavaScriptをPlaywrightサーバーのプロセス内で実行する。RCE(リモートコード実行)相当」というものです。このツールを含むサーバーに接続する場合、許可を出す前に、どんな指示で呼ばれる想定かを確認する価値があります。

送信先の制限(--allowed-origins / --blocked-origins)も、セキュリティ境界としては機能しません。ブラウザがリクエストできる送信先を絞るオプションですが、リダイレクトにも効きません。LLMが誤って想定外のサイトへ操作を広げるのを防ぐ補助にとどまり、悪意ある入力を確実に遮断する仕組みではない点は割り引いて考える必要があります。

設定ファイルのsecretsフィールド(起動オプションでは--secretsでdotenv形式のファイルを渡します)。ツールの応答に含まれる一致した平文を置き換えますが、READMEが「便利機能であってセキュリティ機能ではない」と書くとおり、安全機構ではありません。応答内容はクライアント側で確認する運用が前提です。

ファイルシステムへのアクセスは、既定でワークスペースのルート(ルートが設定されていなければカレントディレクトリ)に限られ、file://URLへの遷移も遮断されます。--allow-unrestricted-file-accessはこの制限を外すので、付ける前に、モデルにワークスペース外のファイルを読ませてよいかを考える必要があります。

既定の制限も誤操作を防ぐ補助で、意図的な回避までは防げません。本当の制限はクライアント側の権限設定で掛けます。

よくあるつまずき

projectスコープで追加したのにツールが使えない

.mcp.jsonのサーバーは、承認するまでPending approvalのままで接続されません。claude mcp get <名前>でStatusを確認し、表示のとおりclaudeを起動して承認します。承認の選択をやり直したいときは、claude mcp reset-project-choicesが、承認済みと拒否済みの記録をこのプロジェクトについてまとめて消します。

cloneしたリポジトリでは、コミット済みの承認設定があっても、ワークスペースを信頼するまでclaude mcp listとgetはPending approvalと表示します。

ヘッドなしで動かしたいのに窓が開く

既定はヘッドありです。ディスプレイのないサーバーやIDEのワーカープロセスからは--headlessを付けます。ヘッドありのまま使うなら、READMEの案内どおりDISPLAYのある環境で--portを指定し、HTTPトランスポートのスタンドアロンサーバーとして起動します。

永続プロファイルが「使用中」でロックされる

同じワークスペースから複数のMCPクライアントを同時に起動すると、永続プロファイルの排他制御に引っかかります。片方に--isolatedを付けるか、--user-data-dirで別ディレクトリを指定すると解消します。

スナップショットが大きすぎてコンテキストを圧迫する

複雑なページのアクセシビリティツリーは要素数が多く、応答が肥大化しがちです。browser_snapshotのdepthパラメータでツリーの深さを制限するか、targetで要素を絞ると出力を抑えられます。操作のたびに応答へスナップショットを付けたくない場合は、起動オプションの--snapshot-mode noneで外し、必要なときにbrowser_snapshotを呼ぶ使い方になります。

DockerでFirefoxやWebKitを使おうとして失敗する

現行のDocker実装はヘッドレスChromiumのみに対応しています。Firefox・WebKitや、ヘッドあり起動が必要な場合はDockerではなくローカルのnpx起動を使います。

stdioとHTTPを取り違えて接続できない

claude mcp addはデフォルトでstdio形式のローカルプロセスとして追加します。既に--portを付けてスタンドアロン起動したサーバーに接続したい場合は、claude mcp add --transport http playwright http://localhost:8931/mcpのようにHTTPエンドポイントを明示する必要があります。接続できないときの切り分け手順はMCPサーバーに接続できないときの切り分け手順にまとめています。

よくある質問

Playwright MCPはAnthropic製ですか?

いいえ、Microsoft製です。@playwright/mcpパッケージはMicrosoftのPlaywrightプロジェクトの一部として公開・保守されています。MCPはAnthropicが公開したプロトコルで、Playwright MCPはその上に載るサードパーティのサーバーという関係です。

生成されるコードの言語は選べますか?

--codegen <lang>で、生成されるコードの言語をtypescript・python・java・csharp・noneから選べます。既定はtypescriptです。

まとめ

Playwright MCPは、claude mcp add playwright -- npx @playwright/mcp@latestの1行でClaude Codeに接続できる、Microsoft製のブラウザ自動化MCPサーバーです。

迷いどころは3つに絞れます。永続プロファイルか--isolatedか、チームで共有するならprojectスコープの承認を挟むか、そして高頻度なブラウザ操作ならCLI+SKILLSも比べるかです。

browser_run_code_unsafeのようにRCE相当の強い権限を持つツールを含む点は、接続前に頭に入れておく価値があります。スコープ・.mcp.json・OAuthの共通仕様はClaude Code MCP設定ガイドが出発点になります。