Playwright MCPサーバーの使い方 — Claude Codeでの導入と設定

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

本記事はPlaywright MCP単体の導入と使いどころに絞ります。MCPプロトコル自体の仕組みはMCPとは、Claude CodeでのMCP設定全般(スコープ・.mcp.json・OAuth認証)はClaude Code MCP設定ガイドを参照してください。

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

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

このサーバーの設計上の特徴は、スクリーンショットではなくPlaywrightのアクセシビリティツリーを使う点です。アクセシビリティツリーとは、ページ内の要素を「ボタン」「リンク」「見出し」といった役割と名前の構造データとして表現したものです。画像を解析するビジョンモデルなしに、テキストベースの構造情報だけで要素を特定できるため、クリックやフォーム入力の対象を取り違えにくくなります。スクリーンショット自体もbrowser_take_screenshotツールで取得できますが、操作の対象特定には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.78のように具体的なバージョン番号を指定します。追加後はclaude mcp listで接続状態を確認するか、セッション内で/mcpを実行するとツール一覧が表示されます。

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

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

コンテキストウィンドウの消費を抑えたいCI寄りの用途ならCLI+SKILLSに分があります。一方で、ブラウザの状態を会話をまたいで保ちながら試行錯誤したい探索的な操作や、他のMCPサーバーと同じ流儀で扱いたい場合はMCPサーバーのままで十分です。どちらも同じPlaywrightエンジンの上に構築されており、片方でしか実現できない機能があるわけではありません。

主要なCLIオプション

Playwright MCPはnpx @playwright/mcp@latestの後ろに渡す起動時オプションで、ブラウザの種類や実行環境を細かく制御できます。オプションは.mcp.jsonのargs配列に並べるか、対応する環境変数(PLAYWRIGHT_MCP_が接頭辞)で渡します。

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

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

Docker経由でも実行できますが、現行のDockerイメージが対応するのはヘッドレスのChromiumだけです。

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

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

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

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

Playwright MCPが公開するツールは、既定で有効な「コア自動化」群と、--capsで明示的に有効化する追加群に分かれます。

コア自動化には、ページ遷移からフォーム操作、状態取得までの一通りが含まれます。

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

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

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

セキュリティ上の注意

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

1つ目はbrowser_run_code_unsafeツールです。任意のJavaScriptコードをPlaywrightサーバーのプロセス内で実行するツールで、公式ドキュメントは「RCE(リモートコード実行)相当」と表現しています。このツールを含むサーバーに接続する場合、Claude Codeの承認フローで許可を出す前に、どんな指示で呼ばれる想定かを確認する価値があります。

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

3つ目は設定ファイルのsecretsフィールドです。ツールの応答に含まれる機密情報をマスクしますが、これも便利機能であって安全機構ではありません。応答内容はクライアント側で確認する運用が前提です。

よくあるつまずき

ヘッドレス環境で起動が固まる

ディスプレイのないサーバーやワーカープロセスでは、既定のヘッドあり起動が失敗またはハングします。--headlessを付けるか、DISPLAY環境変数を用意したうえで--portを指定してHTTPトランスポートのスタンドアロンサーバーとして起動します。

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

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

スナップショットが大きすぎて出力が警告される

複雑なページのアクセシビリティツリーは要素数が多く、応答が肥大化しがちです。browser_snapshotのdepthパラメータでツリーの深さを制限するか、必要な要素だけに絞ったtarget指定を使うと出力を抑えられます。

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が公開しLinux Foundation傘下のAgentic AI Foundationが管理する標準です。プロトコルの詳細はMCPとはで扱っています。

Claude Codeで使う場合、Playwrightのテストコードを書く必要がありますか?

不要です。Playwright MCPはテストコードの代わりに、自然文の指示からブラウザ操作ツールを直接呼び出します。既存のPlaywrightテストスイートを持つプロジェクトでコード生成を併用したい場合は、--codegen typescriptオプションで操作内容をTypeScriptコードとして書き出すこともできます。

無料で使えますか?

パッケージ自体はApache-2.0ライセンスのオープンソースで無料です。費用が発生するとすれば、接続先のサイトの利用規約やAPI課金であり、Playwright MCP自体に利用料はかかりません。

ログイン状態を保持したままブラウザを操作できますか?

できます。既定の永続プロファイルはログイン情報をディスクに保存し、次回起動時も引き継ぎます。テストのように毎回まっさらな状態から始めたい場合は--isolatedオプションに切り替えます。

スクリーンショットとスナップショットは何が違いますか?

browser_take_screenshotは画像としての見た目を返すツールで、browser_snapshotはクリックや入力の対象を特定するための構造化されたアクセシビリティツリーを返すツールです。操作の起点にできるのはスナップショットだけです。スクリーンショットは見た目の確認用にとどまります。

Claude Desktopでも同じサーバーを使えますか?

使えます。標準のJSON設定(command: npx、args: ["@playwright/mcp@latest"])はClaude Code・Claude Desktop・VS Code・Cursorなど主要なMCPクライアントで共通です。Claude Codeではclaude mcp addが同じ設定を生成します。

複数のブラウザタブを同時に扱えますか?

扱えます。browser_tabsツールでタブの作成・切り替え・一覧・クローズを操作でき、1つのブラウザコンテキスト内で複数タブを行き来しながら自動化を組めます。

まとめ

Playwright MCPは、claude mcp add playwright -- npx @playwright/mcp@latestの1行でClaude Codeに接続できる、Microsoft製のブラウザ自動化MCPサーバーです。アクセシビリティツリーによる要素特定を軸に、クリック・入力・スクリーンショット・JavaScript実行までのコア機能が既定で使え、PDF出力や座標ベース操作、デベロッパーツール連携は--capsで必要な分だけ追加します。

導入時に押さえるべき判断は2つです。1つは永続プロファイルか--isolatedかというセッション状態の扱い、もう1つは高頻度なブラウザ操作をコーディングエージェントで回すならPlaywright CLI+SKILLSも選択肢に入るという点です。browser_run_code_unsafeのようにRCE相当の強い権限を持つツールも含まれるため、接続前に承認フローで何が許可されるかを確認しておくと安全です。MCP設定の共通仕様(スコープ・.mcp.json・OAuth)を先に押さえたい場合はClaude Code MCP設定ガイドが出発点になります。