Playwright MCP Server 🎭

---

Playwright MCP サーバー 🎭

Playwright を使用してブラウザー自動化機能を提供する Model Context Protocol サーバーです。このサーバーにより、LLM は Web ページを操作し、スクリーンショットを撮影し、テストコードを生成し、ページのスクレイピングを行い、実際のブラウザー環境で JavaScript を実行できます。

✨ v1.0.10 の新機能

🎯 143 種類の実機プリセットによるデバイスエミュレーション！

簡単なコマンドで、実際のデバイスプロファイル上で Web アプリケーションをテストできます。

// Test on iPhone 13 with automatic user-agent, touch support, and device pixel ratio
await playwright_resize({ device: "iPhone 13" });

// Switch to iPad with landscape orientation
await playwright_resize({ device: "iPad Pro 11", orientation: "landscape" });

// Test desktop view
await playwright_resize({ device: "Desktop Chrome" });

AI アシスタント向けの自然言語サポート：

• 「iPhone 13 でテスト」
• 「iPad 表示に切り替え」
• 「横向きに回転」

143 種類のデバイスに対応： iPhone、iPad、Pixel、Galaxy、デスクトップブラウザーで、ビューポート、ユーザーエージェント、タッチイベント、デバイスのピクセル比を適切にエミュレートします。

📚 デバイスクイックリファレンスを見る | プロンプトガイド

スクリーンショット

ドキュメント | API リファレンス

インストール

npm、mcp-get、または Smithery を使用してパッケージをインストールできます。

npm を使用する場合：

npm install -g @executeautomation/playwright-mcp-server

mcp-get を使用する場合：

npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server

Smithery を使用する場合

Smithery を使って、Claude Desktop 用の Playwright MCP を自動的にインストールするには：

npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude

Claude Code を使用する場合：

claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server

VS Code へのインストール

以下のいずれかのボタンを使って、VS Code に Playwright MCP サーバーをインストールします。

また、VS Code CLI を使って Playwright MCP サーバーをインストールすることもできます。

# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}'

# For VS Code Insiders
code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}'

インストール後、ExecuteAutomation Playwright MCP サーバーを VS Code の GitHub Copilot エージェントで使用できるようになります。

ブラウザーのインストール

自動インストール（推奨）

Playwright MCP Server は、初回使用時にブラウザーのバイナリを自動的にインストールします。ブラウザーが不足していることをサーバーが検出すると、次の処理を行います。

1. 必要なブラウザー（Chromium、Firefox、または WebKit）を自動的にダウンロードしてインストールします
2. コンソールにインストールの進行状況を表示します
3. インストール完了後、リクエストを再試行します

手動でのセットアップは不要です！ サーバーを起動して使用するだけで、ブラウザーのインストールはサーバーが処理します。

手動インストール（任意）

ブラウザーを手動でインストールする場合や、自動インストールで問題が発生した場合は、次の手順に従ってください。

# Install all browsers
npx playwright install

# Or install specific browsers
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

ブラウザーの保存場所

ブラウザーは次の場所にインストールされます。

• Windows: %USERPROFILE%\AppData\Local\ms-playwright
• macOS: ~/Library/Caches/ms-playwright
• Linux: ~/.cache/ms-playwright

Playwright Server を使用するための設定

標準モード（stdio）

これはClaude Desktop に推奨されるモードです。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

注: stdio モードでは、JSON-RPC 通信をクリーンに保つため、ログはコンソールではなくファイルのみに自動的に出力されます。ログは ~/playwright-mcp-server.log に書き込まれます。

HTTP モード（スタンドアロンサーバー）

ディスプレイのないシステムや IDE のワーカープロセスから、ブラウザーをヘッド付きで実行する場合は、MCP サーバーをスタンドアロンの HTTP サーバーとして実行できます。

Claude Desktop ユーザーへの注: 現在、Claude Desktop では stdio モード（command/args 設定）が必要です。HTTP モードは VS Code、カスタムクライアント、リモートデプロイに推奨されます。詳細は CLAUDE_DESKTOP_CONFIG.md をご覧ください。

HTTP サーバーの起動

# Using npx
npx @executeautomation/playwright-mcp-server --port 8931

# Or after global installation
playwright-mcp-server --port 8931

サーバーが起動し、利用可能なエンドポイントが表示されます。

==============================================
Playwright MCP Server (HTTP Mode)
==============================================
Port: 8931

ENDPOINTS:
- SSE Stream:     GET  http://localhost:8931/sse
- Messages:       POST http://localhost:8931/messages?sessionId=<id>
- MCP (unified):  GET  http://localhost:8931/mcp
- MCP (unified):  POST http://localhost:8931/mcp?sessionId=<id>
- Health Check:   GET  http://localhost:8931/health
==============================================

HTTP モードのクライアント設定

⚠️ 重要: HTTP/SSE トランスポートでは "type": "http" フィールドが必須です！

VS Code GitHub Copilot の場合：

{
  "github.copilot.chat.mcp.servers": {
    "playwright": {
      "url": "http://localhost:8931/mcp",
      "type": "http"
    }
  }
}

カスタム MCP クライアントの場合：

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp",
      "type": "http"
    }
  }
}

重要: "type": "http" がない場合、接続に失敗します。

Claude Desktop の場合： 代わりに stdio モードを使用してください（上記の標準モードを参照）。

HTTP モードのユースケース

• ディスプレイのないシステム（リモートサーバーなど）で、ブラウザーをヘッド付きで実行する
• VS Code GitHub Copilot と統合する
• サーバーをバックグラウンドサービスとして実行する
• 複数のクライアントからサーバーにアクセスする
• /health エンドポイントでデバッグする
• カスタム MCP クライアントと統合する

モニタリング: サーバーには、競合を避けるため動的に割り当てられたポートで起動するモニタリングシステムが含まれています。実際のポートはコンソール出力で確認してください。

注: 当面、Claude Desktop では引き続き stdio モード（上記の標準モード）を使用してください。

トラブルシューティング

「No transport found for sessionId」エラー

症状: 「Bad Request: No transport found for sessionId」というメッセージが表示される 400 エラー

解決策:

1. 設定に "type": "http" が含まれていることを確認する

   {
     "url": "http://localhost:8931/mcp",
     "type": "http"  // ← This is REQUIRED!
   }
   

2. サーバーログに接続が表示されていることを確認する：

   # Should see these in order:
   # 1. "Incoming request" - GET /mcp
   # 2. "Transport registered" - with sessionId
   # 3. "POST message received" - with same sessionId
   

3. サーバーとクライアントの両方を再起動する

接続の問題

• サーバーが起動しない: ポート 8931 が使用可能か確認してください
• 外部からのアクセスがブロックされる: これはセキュリティ上の設計です。サーバーは localhost のみにバインドします
• リモートアクセスの場合: SSH トンネリングを使用してください。

  ssh -L 8931:localhost:8931 user@remote-server
  

テスト

このプロジェクトではテストに Jest を使用しています。テストは src/__tests__ ディレクトリにあります。

テストの実行

次のいずれかのコマンドを使用してテストを実行できます。

# Run tests using the custom script (with coverage)
node run-tests.cjs

# Run tests using npm scripts
npm test           # Run tests without coverage
npm run test:coverage  # Run tests with coverage
npm run test:custom    # Run tests with custom script (same as node run-tests.cjs)

テストカバレッジレポートは coverage ディレクトリに生成されます。

evals の実行

evals パッケージは MCP クライアントを読み込み、その後 index.ts ファイルを実行するため、テスト間で再ビルドする必要はありません。npx コマンドの前に環境変数を指定して読み込めます。詳細なドキュメントはこちらをご覧ください。

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/tools/codegen/index.ts

貢献

新しいツールを追加する際は、ツール名の長さにご注意ください。Cursor など一部のクライアントでは、サーバー名とツール名を合わせた長さ（server_name:tool_name）が60文字までに制限されています。

サーバー名はplaywright-mcpです。この制限を超えないよう、ツール名を短くしてください。

Star History