Playwright MCPをつなぐ｜追加・起動・確認

AIアプリからブラウザを操作させたくて、MCP（Model Context Protocol、AIアプリと外部ツールをつなぐ共通規格）ごしにPlaywrightを使おうとすると、最初に迷うポイントがあります。Client（Cursor や Claude Desktop など、実際に使っているAIアプリ）へのサーバー追加と、Playwright自体の起動やブラウザ操作の確認は、似ているようで別の作業です。

この記事では、公式のPlaywright MCP Server（@playwright/mcp）をつなぐときの順番と、起動の形、意図した操作が通っているかの確認、そしてうまくいかないときにどこへ戻ればよいかを整理します。手順は公式ドキュメント（playwright.devおよびmicrosoft/playwright-mcpのREADME）に沿ってまとめたもので、実機で接続した結果ではありません。

どのMCPサーバーを選ぶかという比較、使っているアプリごとの画面操作の細部、権限まわりの点検を最後まで終わらせる作業、そしてPlaywrightでテストコードを書く方法は、この記事では扱いません。必要になったときは、関連記事や公式ドキュメントで確認してください。

今日の結論

• Clientへのサーバー追加と、Playwright側の起動・スナップショット操作の理解は別の作業です。先に揃えるのは、対象パッケージ（@playwright/mcp）とClientへの追加形です。
• 進める順番は「公式で対象パッケージを確認する→Clientに追加する（必要ならHTTPのurl）→意図したブラウザ操作を1回呼べるか確認する→止まったら起動・接続・権限のどこに戻るか判断する」の流れです。
• ページの操作は、画面のピクセルではなくアクセシビリティスナップショット（要素の構造を表したテキスト情報）経由という公式の説明に沿います。設定例やログに認証情報の実値は書きません。
• 選定比較、権限の深い見直し、使うアプリの画面操作の細部、テストコードの書き方は、この記事では扱いません。
• つながったかどうか、安全かどうかは、公式ドキュメントと使っているアプリ・ブラウザの画面で確認します。

まず整理：使うアプリへの追加とPlaywright側の起動は別作業

Playwright MCPを使い始めるとき、Client（利用アプリ）への追加と、Playwright自体の起動は、同じ「ブラウザとMCP」という話題として一つの作業のように扱われがちです。ですが、この二つは触る場所が違います。

Clientへの追加は、CursorやClaude Desktopなど、普段使っているアプリの設定にMCPサーバーの情報を書き込む作業です。一方でPlaywright側の起動は、@playwright/mcpというパッケージが実際にブラウザを動かし、ページの状態をスナップショットとしてやり取りする部分に当たります。先に確認しておきたいのは、この二つを混ぜずに、対象パッケージとClientへの追加形をそろえることです。

どのMCPサーバーを選ぶかという比較や、Clientごとの画面操作の細部は、この記事では扱いません。関連記事や各公式ドキュメントを参照してください。

進める順番：対象確認→追加と起動→確認

順番を先に一覧にすると、次のとおりです。

まず、公式ドキュメントで対象パッケージの表記を確認します。標準的な設定は、commandにnpx、argsに@playwright/mcp@latestを指定する形です。VS CodeやCursor、Claude Code、Claude Desktopなど、多くのClientでこの形がそのまま使えます。

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

追加できたら、次は起動の確認です。AIアプリ側から、特定のページを開いて見出しを教えてほしいというような、具体的な操作を1つ頼んでみます。応答の中でブラウザが開き、ページの状態を読み取れていれば、追加と起動の両方がひとまず通っている合図です。ここでのポイントは、画面のピクセルを見せるのではなく、アクセシビリティスナップショットというテキストの構造情報を介してAIがページを把握する点です。スクリーンショットに頼る仕組みとは、確認のしかたが少し違います。

設定ファイルの書き方そのものを一から見直したい場合は、JSON設定の書き方も参考になります。

止まったときの戻り先

追加したのにブラウザが開かない、ツールが呼べない、というときは、症状によって見る場所が変わります。

• 起動: Node.jsのバージョンやコマンドの打ち間違い、ブラウザ本体が入っていないなど、Playwright自体が立ち上がっていないケースです。まずはターミナルでコマンド単体を実行し、エラーメッセージを確認します。
• 接続: Client側の設定でサーバーが認識されていないケースです。標準のstdio形式か、HTTPのurl形式か、設定の食い違いがないかを見直します。
• 権限: サーバー自体は動いているのに、特定の操作だけ止まるケースです。公式ドキュメントが示すアクセス制御の設定を確認します。深い見直しは権限まわりの記事にまとめています。

戻り先を切り分けるコツは、エラーメッセージがどの段階で出ているかを見ることです。起動なのか、接続なのか、権限なのか。三つの切り分けです。ここを区別できると、次に見る場所が絞れます。ログや設定例には、認証情報の実値を書かないようにしてください。

起動形と注意：stdio／HTTPと公式が示す限界

Playwright MCPには、既定のstdio形式と、--portを指定して立ち上げるHTTP形式があります。

HTTP形式は、ブラウザを画面表示なしで動かす環境や、IDEのワーカープロセスから画面にアクセスできない場合に向いています。この場合は先にサーバーを単体で起動し、Client側の設定はurlを指定する形に変わります。手元とURLでの違いを比較で詳しく見たい場合は、手元とURLの違いを整理した記事を参照してください。

公式のREADMEには、Playwright MCP単体をセキュリティの境界として扱わない旨の注意があります。単体では守りを完結できないため、本番運用に近づけるほど、アクセス制御の設定を別途確認する必要があります。Dockerでの起動例も公式にあります。手順の全集はこの記事では扱いません。

決めたあとに進む選定・権限・アプリ操作

ここまでの順番を一通り確認できたら、次に進む先は目的によって分かれます。

ほかのMCPサーバーの候補を見比べたい場合は、MCPサーバーのおすすめ一覧が候補の見方の参考になります。権限の見直しをもう少し丁寧に進めたい場合は、先ほど触れた権限まわりの記事にチェックリストがあります。使っているアプリ側の設定を細かく確認したいときは、Cursorの設定手順やClaude Desktopの設定手順、Claude Codeの設定手順、VS Codeの設定手順が、それぞれの画面に沿って書かれています。

対象パッケージとClientへの追加、そして起動確認までができていれば、使い始められます。

まとめ／次に読む

Clientへの追加とPlaywright側の起動は別の作業で、先に対象パッケージと追加形をそろえることが出発点です。公式で対象を確認する、Clientに追加する、操作を確認するという順番を踏み、止まったときは起動・接続・権限のどこに当たるかで戻り先を切り分けます。stdioとHTTPの使い分けや、セキュリティの境界ではないという公式の注意も、同じ順番の延長で確認します。

MCP全体の読み方や用語を最初から整理したい場合は、MCPガイドから関連記事をたどれます。

本記事の内容は執筆時点（2026-09-24）の情報に基づきます。MCPおよびPlaywright公式MCP Serverの公式ドキュメントを参照しており、掲載の順番は実機でPlaywright MCPをつないだ結果ではありません。接続の成功、安全性、全Client同一手順を保証するものではありません。Serverの版やブラウザ環境によって手順は異なります。重要な判断は公式ドキュメントで確認してください。