🚀 Playwright MCP
Playwright MCPは、Playwrightを使用してブラウザ自動化機能を提供するモデルコンテキストプロトコル（MCP）サーバーです。このサーバーにより、LLM（大規模言語モデル）は構造化されたアクセシビリティスナップショットを介してウェブページと相互作用することができ、スクリーンショットや視覚調整モデルを必要としなくなります。
✨ 主な機能
- 高速かつ軽量：Playwrightのアクセシビリティツリーを使用し、ピクセルベースの入力を必要としません。
- LLMに友好的：ビジョンモデルを必要とせず、構造化データのみで動作します。
- 決定論的なツール適用：スクリーンショットベースのアプローチで一般的な曖昧さを回避します。
📦 インストール
必要条件
- Node.js 18以上
- VS Code、Cursor、Windsurf、Claude Desktop、Gooseまたはその他のMCPクライアント
始めるには
まず、クライアントでPlaywright MCPサーバーをインストールします。
標準設定は、ほとんどのツールで機能します。
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
Claude Code
Claude Code CLIを使用してPlaywright MCPサーバーを追加します。
claude mcp add playwright npx @playwright/mcp@latest
Claude Desktop
MCPのインストールガイドに従い、上記の標準設定を使用します。
Cursor
ボタンをクリックしてインストールする：
または手動でインストールする：
Cursor Settings -> MCP -> Add new MCP Serverに移動します。好きな名前を付け、commandタイプでnpx @playwright/mcpを使用します。Editをクリックして設定を確認またはコマンド引数を追加することもできます。
Gemini CLI
MCPのインストールガイドに従い、上記の標準設定を使用します。
Goose
ボタンをクリックしてインストールする：
または手動でインストールする：
Advanced settings -> Extensions -> Add custom extensionに移動します。好きな名前を付け、タイプにSTDIOを使用し、commandをnpx @playwright/mcpに設定します。「Add Extension」をクリックします。
LM Studio
ボタンをクリックしてインストールする：
または手動でインストールする：
右側のサイドバーのProgram -> Install -> Edit mcp.jsonに移動し、上記の標準設定を使用します。
Qodo Gen
VSCodeまたはIntelliJでQodo Genチャットパネルを開き → 「Connect more tools」 → 「+ Add new MCP」 → 上記の標準設定を貼り付けます。
「Save」をクリックします。
VS Code
ボタンをクリックしてインストールする：
または手動でインストールする：
MCPのインストールガイドに従い、上記の標準設定を使用します。VS Code CLIを使用してPlaywright MCPサーバーをインストールすることもできます。
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
インストール後、Playwright MCPサーバーはVS Code内のGitHub Copilotエージェントで使用できるようになります。
Windsurf
Windsurf MCPのドキュメントに従い、上記の標準設定を使用します。
📚 ドキュメント
設定
Playwright MCPサーバーは、以下の引数をサポートしています。これらは、上記のJSON設定の"args"リストの一部として提供できます。
> npx @playwright/mcp@latest --help
--allowed-origins <origins> ブラウザがリクエストを許可するオリジンのセミコロン区切りのリスト。デフォルトはすべて許可。
--blocked-origins <origins> ブラウザがリクエストをブロックするオリジンのセミコロン区切りのリスト。ブロックリストは許可リストの前に評価されます。許可リストなしで使用する場合、ブロックリストに一致しないリクエストは依然として許可されます。
--block-service-workers サービスワーカーをブロックする
--browser <browser> 使用するブラウザまたはChromeチャネル。可能な値: chrome, firefox, webkit, msedge。
--caps <caps> 有効にする追加機能のカンマ区切りのリスト。可能な値: vision, pdf。
--cdp-endpoint <endpoint> 接続するCDPエンドポイント。
--config <path> 設定ファイルへのパス。
--device <device> エミュレートするデバイス。例: "iPhone 15"
--executable-path <path> ブラウザ実行ファイルへのパス。
--headless ブラウザをヘッドレスモードで実行する。デフォルトはヘッド付き。
--host <host> サーバーをバインドするホスト。デフォルトはlocalhost。すべてのインターフェースにバインドするには0.0.0.0を使用。
--ignore-https-errors HTTPSエラーを無視する
--isolated ブラウザプロファイルをメモリ内に保持し、ディスクに保存しない。
--image-responses <mode> クライアントに画像レスポンスを送信するかどうか。"allow"または"omit"が可能。デフォルトは"allow"。
--no-sandbox 通常はサンドボックス化されるすべてのプロセスタイプのサンドボックスを無効にする。
--output-dir <path> 出力ファイルのディレクトリへのパス。
--port <port> SSEトランスポートでリッスンするポート。
--proxy-bypass <bypass> プロキシをバイパスするカンマ区切りのドメイン。例: ".com,chromium.org,.domain.com"
--proxy-server <proxy> プロキシサーバーを指定する。例: "http://myproxy:3128" または "socks5://myproxy:8080"
--save-session Playwright MCPセッションを出力ディレクトリに保存するかどうか。
--save-trace セッションのPlaywright Traceを出力ディレクトリに保存するかどうか。
--storage-state <path> 分離されたセッションのストレージ状態ファイルへのパス。
--user-agent <ua string> ユーザーエージェント文字列を指定する
--user-data-dir <path> ユーザーデータディレクトリへのパス。指定されない場合、一時ディレクトリが作成されます。
--viewport-size <size> ブラウザのビューポートサイズをピクセルで指定する。例: "1280, 720"
ユーザープロファイル
Playwright MCPは、通常のブラウザのように永続的なプロファイルで実行することも（デフォルト）、テストセッション用の分離されたコンテキストで実行することもできます。
永続的なプロファイル
すべてのログイン情報は永続的なプロファイルに保存され、オフライン状態をクリアしたい場合はセッション間で削除することができます。
永続的なプロファイルは以下の場所にあり、--user-data-dir引数で上書きすることができます。
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile
- ~/.cache/ms-playwright/mcp-{channel}-profile
分離モード
分離モードでは、各セッションは分離されたプロファイルで開始されます。MCPにブラウザを閉じるように要求するたびに、セッションが閉じられ、このセッションのすべてのストレージ状態が失われます。設定のcontextOptionsまたは--storage-state引数を介して、ブラウザに初期ストレージ状態を提供することができます。ストレージ状態の詳細については、こちらを参照してください。
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--isolated",
"--storage-state={path/to/storage.json}"
]
}
}
}
設定ファイル
Playwright MCPサーバーは、JSON設定ファイルを使用して構成することができます。--configコマンドラインオプションを使用して設定ファイルを指定することができます。
npx @playwright/mcp@latest --config path/to/config.json
設定ファイルのスキーマ
```typescript
{
// ブラウザ設定
browser?: {
// 使用するブラウザタイプ (chromium, firefox, または webkit)
browserName?: 'chromium' | 'firefox' | 'webkit';
// ブラウザプロファイルをメモリ内に保持し、ディスクに保存しない。
isolated?: boolean;
// ブラウザプロファイルの永続化のためのユーザーデータディレクトリへのパス
userDataDir?: string;
// ブラウザ起動オプション (Playwrightドキュメントを参照)
// @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
launchOptions?: {
channel?: string; // ブラウザチャネル (例: 'chrome')
headless?: boolean; // ヘッドレスモードで実行する
executablePath?: string; // ブラウザ実行ファイルへのパス
// ... その他のPlaywright起動オプション
};
// ブラウザコンテキストオプション
// @see https://playwright.dev/docs/api/class-browser#browser-new-context
contextOptions?: {
viewport?: { width: number, height: number };
// ... その他のPlaywrightコンテキストオプション
};
// 既存のブラウザに接続するためのCDPエンドポイント
cdpEndpoint?: string;
// リモートPlaywrightサーバーエンドポイント
remoteEndpoint?: string;
},
// サーバー設定
server?: {
port?: number; // リッスンするポート
host?: string; // バインドするホスト (デフォルト: localhost)
},
// 追加機能のリスト
capabilities?: Array<
'tabs' | // タブ管理
'install' | // ブラウザインストール
'pdf' | // PDF生成
'vision' | // 座標ベースの相互作用
;
// 出力ファイルのディレクトリ
outputDir?: string;
// ネットワーク設定
network?: {
// ブラウザがリクエストを許可するオリジンのリスト。デフォルトはすべて許可。allowedOriginsとblockedOriginsの両方に一致するオリジンはブロックされます。
allowedOrigins?: string[];
// ブラウザがリクエストをブロックするオリジンのリスト。`allowedOrigins`と`blockedOrigins`の両方に一致するオリジンはブロックされます。
blockedOrigins?: string[];
};
/**
- クライアントに画像レスポンスを送信するかどうか。"allow"または"omit"が可能。
- デフォルトは"allow"。
*/
imageResponses?: 'allow' | 'omit';
}
</details>
### スタンドアロンMCPサーバー
ディスプレイのないシステムでヘッド付きブラウザを実行する場合、またはIDEのワーカープロセスから実行する場合、DISPLAYが設定された環境からMCPサーバーを実行し、`--port`フラグを渡してHTTPトランスポートを有効にします。
```bash
npx @playwright/mcp@latest --port 8931
そして、MCPクライアントの設定で、urlをHTTPエンドポイントに設定します。
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/mcp"
}
}
}
Docker
注意: Docker実装は現在、ヘッドレスChromiumのみをサポートしています。
{
"mcpServers": {
"playwright": {
"command": "docker",
"args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
}
}
}
Dockerイメージを自分でビルドすることもできます。
docker build -t mcr.microsoft.com/playwright/mcp .
プログラムによる使用
```js
import http from 'http';
import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
http.createServer(async (req, res) => {
// ...
// ヘッドレスPlaywright MCPサーバーをSSEトランスポートで作成する
const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
const transport = new SSEServerTransport('/messages', res);
await connection.sever.connect(transport);
// ...
});
</details>
### ツール
<details>
<summary><b>コア自動化</b></summary>
- **browser_click**
- タイトル: クリック
- 説明: ウェブページ上でクリックを実行する
- パラメーター:
- `element` (string): 要素との相互作用の許可を取得するために使用される人間が読める要素の説明
- `ref` (string): ページスナップショットからの正確なターゲット要素の参照
- `doubleClick` (boolean, オプション): 単一クリックではなくダブルクリックを実行するかどうか
- `button` (string, オプション): クリックするボタン。デフォルトは左
- 読み取り専用: **false**
- **browser_close**
- タイトル: ブラウザを閉じる
- 説明: ページを閉じる
- パラメーター: なし
- 読み取り専用: **true**
- **browser_console_messages**
- タイトル: コンソールメッセージを取得する
- 説明: すべてのコンソールメッセージを返す
- パラメーター: なし
- 読み取り専用: **true**
- **browser_drag**
- タイトル: マウスをドラッグする
- 説明: 2つの要素間でドラッグアンドドロップを実行する
- パラメーター:
- `startElement` (string): 要素との相互作用の許可を取得するために使用される人間が読めるソース要素の説明
- `startRef` (string): ページスナップショットからの正確なソース要素の参照
- `endElement` (string): 要素との相互作用の許可を取得するために使用される人間が読めるターゲット要素の説明
- `endRef` (string): ページスナップショットからの正確なターゲット要素の参照
- 読み取り専用: **false**
- **browser_evaluate**
- タイトル: JavaScriptを評価する
- 説明: ページまたは要素上でJavaScript式を評価する
- パラメーター:
- `function` (string): () => { /* コード */ } または要素が提供された場合は (element) => { /* コード */ }
- `element` (string, オプション): 要素との相互作用の許可を取得するために使用される人間が読める要素の説明
- `ref` (string, オプション): ページスナップショットからの正確なターゲット要素の参照
- 読み取り専用: **false**
- **browser_file_upload**
- タイトル: ファイルをアップロードする
- 説明: 1つまたは複数のファイルをアップロードする
- パラメーター:
- `paths` (array): アップロードするファイルの絶対パス。単一のファイルまたは複数のファイルを指定できます。
- 読み取り専用: **false**
- **browser_handle_dialog**
- タイトル: ダイアログを処理する
- 説明: ダイアログを処理する
- パラメーター:
- `accept` (boolean): ダイアログを受け入れるかどうか。
- `promptText` (string, オプション): プロンプトダイアログの場合のプロンプトのテキスト。
- 読み取り専用: **false**
- **browser_hover**
- タイトル: マウスをホバーする
- 説明: ページ上の要素にマウスをホバーする
- パラメーター:
- `element` (string): 要素との相互作用の許可を取得するために使用される人間が読める要素の説明
- `ref` (string): ページスナップショットからの正確なターゲット要素の参照
- 読み取り専用: **true**
- **browser_navigate**
- タイトル: URLに移動する
- 説明: URLに移動する
- パラメーター:
- `url` (string): 移動するURL
- 読み取り専用: **false**
- **browser_navigate_back**
- タイトル: 前のページに戻る
- 説明: 前のページに戻る
- パラメーター: なし
- 読み取り専用: **true**
- **browser_navigate_forward**
- タイトル: 次のページに進む
- 説明: 次のページに進む
- パラメーター: なし
- 読み取り専用: **true**
- **browser_network_requests**
- タイトル: ネットワークリクエストをリストする
- 説明: ページの読み込み後のすべてのネットワークリクエストを返す
- パラメーター: なし
- 読み取り専用: **true**
- **browser_press_key**
- タイトル: キーを押す
- 説明: キーボードのキーを押す
- パラメーター:
- `key` (string): 押すキーの名前または生成する文字。例: `ArrowLeft` または `a`
- 読み取り専用: **false**
- **browser_resize**
- タイトル: ブラウザウィンドウをリサイズする
- 説明: ブラウザウィンドウをリサイズする
- パラメーター:
- `width` (number): ブラウザウィンドウの幅
- `height` (number): ブラウザウィンドウの高さ
- 読み取り専用: **true**
- **browser_select_option**
- タイトル: オプションを選択する
- 説明: ドロップダウンでオプションを選択する
- パラメーター:
- `element` (string): 要素との相互作用の許可を取得するために使用される人間が読める要素の説明
- `ref` (string): ページスナップショットからの正確なターゲット要素の参照
- `values` (array): ドロップダウンで選択する値の配列。単一の値または複数の値を指定できます。
- 読み取り専用: **false**
- **browser_snapshot**
- タイトル: ページスナップショット
- 説明: 現在のページのアクセシビリティスナップショットを取得する。これはスクリーンショットよりも優れています。
- パラメーター: なし
- 読み取り専用: **true**
- **browser_take_screenshot**
- タイトル: スクリーンショットを撮る
- 説明: 現在のページのスクリーンショットを撮る。スクリーンショットに基づいてアクションを実行することはできません。アクションには`browser_snapshot`を使用してください。
- パラメーター:
- `raw` (boolean, オプション): 圧縮せずに返すかどうか (PNG形式)。デフォルトはfalseで、JPEG画像が返されます。
- `filename` (string, オプション): スクリーンショットを保存するファイル名。指定されない場合は `page-{timestamp}.{png|jpeg}` になります。
- `element` (string, オプション): 要素のスクリーンショットを撮る許可を取得するために使用される人間が読める要素の説明。指定されない場合はビューポートのスクリーンショットが撮られます。要素が指定された場合は、`ref`も指定する必要があります。
- `ref` (string, オプション): ページスナップショットからの正確なターゲット要素の参照。指定されない場合はビューポートのスクリーンショットが撮られます。`ref`が指定された場合は、`element`も指定する必要があります。
- `fullPage` (boolean, オプション): trueの場合、現在表示されているビューポートではなく、スクロール可能な全ページのスクリーンショットを撮ります。要素のスクリーンショットと一緒に使用することはできません。
- 読み取り専用: **true**
- **browser_type**
- タイトル: テキストを入力する
- 説明: 編集可能な要素にテキストを入力する
- パラメーター:
- `element` (string): 要素との相互作用の許可を取得するために使用される人間が読める要素の説明
- `ref` (string): ページスナップショットからの正確なターゲット要素の参照
- `text` (string): 要素に入力するテキスト
- `submit` (boolean, オプション): 入力したテキストを送信するかどうか (Enterキーを押す)
- `slowly` (boolean, オプション): 1文字ずつ入力するかどうか。ページ内のキーハンドラーをトリガーするのに便利です。デフォルトではテキスト全体が一度に入力されます。
- 読み取り専用: **false**
- **browser_wait_for**
- タイトル: 待機する
- 説明: テキストの表示または消滅、または指定された時間の経過を待つ
- パラメーター:
- `time` (number, オプション): 待機する時間 (秒)
- `text` (string, オプション): 待つテキスト
- `textGone` (string, オプション): 消えるのを待つテキスト
- 読み取り専用: **true**
</details>
<details>
<summary><b>タブ管理</b></summary>
- **browser_tab_close**
- タイトル: タブを閉じる
- 説明: タブを閉じる
- パラメーター:
- `index` (number, オプション): 閉じるタブのインデックス。指定されない場合は現在のタブが閉じられます。
- 読み取り専用: **false**
- **browser_tab_list**
- タイトル: タブをリストする
- 説明: ブラウザのタブをリストする
- パラメーター: なし
- 読み取り専用: **true**
- **browser_tab_new**
- タイトル: 新しいタブを開く
- 説明: 新しいタブを開く
- パラメーター:
- `url` (string, オプション): 新しいタブで移動するURL。指定されない場合は新しいタブは空白になります。
- 読み取り専用: **true**
- **browser_tab_select**
- タイトル: タブを選択する
- 説明: インデックスでタブを選択する
- パラメーター:
- `index` (number): 選択するタブのインデックス
- 読み取り専用: **true**
</details>
<details>
<summary><b>ブラウザインストール</b></summary>
- **browser_install**
- タイトル: 設定で指定されたブラウザをインストールする
- 説明: 設定で指定されたブラウザをインストールする。ブラウザがインストールされていないというエラーが発生した場合は、これを呼び出してください。
- パラメーター: なし
- 読み取り専用: **false**
</details>
<details>
<summary><b>座標ベース (--caps=visionでオプトイン)</b></summary>
- **browser_mouse_click_xy**
- タイトル: クリック
- 説明: 指定された位置で左マウスボタンをクリックする
- パラメーター:
- `element` (string): 要素との相互作用の許可を取得するために使用される人間が読める要素の説明
- `x` (number): X座標
- `y` (number): Y座標
- 読み取り専用: **false**
- **browser_mouse_drag_xy**
- タイトル: マウスをドラッグする
- 説明: 指定された位置に左マウスボタンをドラッグする
- パラメーター:
- `element` (string): 要素との相互作用の許可を取得するために使用される人間が読める要素の説明
- `startX` (number): 開始X座標
- `startY` (number): 開始Y座標
- `endX` (number): 終了X座標
- `endY` (number): 終了Y座標
- 読み取り専用: **false**
- **browser_mouse_move_xy**
- タイトル: マウスを移動する
- 説明: 指定された位置にマウスを移動する
- パラメーター:
- `element` (string): 要素との相互作用の許可を取得するために使用される人間が読める要素の説明
- `x` (number): X座標
- `y` (number): Y座標
- 読み取り専用: **true**
</details>
<details>
<summary><b>PDF生成 (--caps=pdfでオプトイン)</b></summary>
- **browser_pdf_save**
- タイトル: PDFとして保存する
- 説明: ページをPDFとして保存する
- パラメーター:
- `filename` (string, オプション): PDFを保存するファイル名。指定されない場合は `page-{timestamp}.pdf` になります。
- 読み取り専用: **true**
</details>
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
