Playwright MCP

What is Playwright MCP?

Playwright MCP is a Model Context Protocol (MCP) server that leverages Playwright to provide browser automation capabilities. It enables Large Language Models (LLMs) to interact with web pages using structured accessibility snapshots, eliminating the need for screenshots or visually-tuned models. By operating on structured data rather than pixel-based input, Playwright MCP offers a lightweight and deterministic approach to browser automation, making it ideal for tasks like web navigation, form-filling, data extraction, and automated testing driven by LLMs.

Key Features of Playwright MCP

• Fast and Lightweight: Utilizes Playwright's accessibility tree for efficient interaction without relying on pixel-based input.
• LLM-Friendly: Operates purely on structured data, removing the need for vision models and simplifying integration with LLMs.
• Deterministic Tool Application: Avoids ambiguity common with screenshot-based approaches, ensuring reliable tool execution.
• Cross-Browser Support: Compatible with Chromium, WebKit, and Firefox, allowing seamless testing and automation across different browsers.
• Cross-Platform: Works on Windows, Linux, and macOS, both locally and in CI/CD environments.
• Multiple Contexts: Supports testing scenarios involving multiple tabs, origins, and users within a single test.
• Trusted Events: Generates real browser input events that mimic user interactions.
• Shadow DOM and Frames: Seamlessly interacts with shadow DOM and frames for complex web applications.

How to Use Playwright MCP

Installation

1. In VS Code:

   • Use the VS Code CLI to install the Playwright MCP server:

     code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
     

   • For VS Code Insiders:

     code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
     

2. Programmatic Usage:

   • Create a server programmatically using custom transports:

     import { createServer } from '@playwright/mcp';
     const server = createServer({ launchOptions: { headless: true } });
     transport = new SSEServerTransport("/messages", res);
     server.connect(transport);
     

Configuration

• Example Configuration:

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

Running Modes

• Snapshot Mode (Default):

  • Uses accessibility snapshots for better performance and reliability.
  • Tools available include browser_navigate, browser_click, browser_type, and more.

• Vision Mode:

  • Uses screenshots for visual-based interactions.
  • Enable Vision Mode by adding the --vision flag:

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

Pricing and Availability

Playwright MCP is open-source and freely available for use. It is built on top of Playwright, which is also open-source and maintained by Microsoft. There are no direct costs associated with using Playwright MCP, though you may need to consider infrastructure costs for running the server in production environments.

Helpful Tips for Using Playwright MCP

1. Optimize Performance:

   • Use headless mode for background operations to reduce resource usage.
   • Clear the user data directory between sessions to avoid state pollution:

     # Windows
     %USERPROFILE%\AppData\Local\ms-playwright\mcp-chrome-profile
     # macOS
     ~/Library/Caches/ms-playwright/mcp-chrome-profile
     # Linux
     ~/.cache/ms-playwright/mcp-chrome-profile
     

2. Debugging:

   • Use the Playwright Inspector to debug tests and generate selectors.
   • Capture execution traces, videos, and screenshots to investigate failures.

3. Tool Selection:

   • Choose Snapshot Mode for most tasks due to its efficiency and reliability.
   • Use Vision Mode only when visual interactions are necessary.

4. Integration with LLMs:

   • Leverage structured data from accessibility snapshots to guide LLM-driven automation.
   • Combine with GitHub Copilot or other agents for enhanced productivity.

Frequently Asked Questions

Q: How does Playwright MCP differ from traditional screenshot-based tools?

A: Playwright MCP uses structured accessibility snapshots instead of pixel-based input, making it faster, more reliable, and eliminating the need for vision models. This approach avoids ambiguity and ensures deterministic tool application.

Q: Can I use Playwright MCP with multiple browsers?

A: Yes, Playwright MCP supports Chromium, WebKit, and Firefox. You can specify the browser using the --browser flag:

npx @playwright/mcp@latest --browser firefox

Q: How do I run Playwright MCP in headless mode?

A: Add the --headless flag to run the browser in headless mode:

npx @playwright/mcp@latest --headless

Q: What is the difference between Snapshot Mode and Vision Mode?

A: Snapshot Mode uses accessibility snapshots for better performance and reliability, while Vision Mode uses screenshots for visual-based interactions. Snapshot Mode is recommended for most tasks, while Vision Mode is useful for scenarios requiring coordinate-based interactions.

Q: How can I debug Playwright MCP tests?

A: Use the Playwright Inspector to step through test execution, inspect pages, generate selectors, and explore execution logs. Additionally, capture traces to investigate test failures with detailed screencasts and DOM snapshots.

Q: Is Playwright MCP compatible with CI/CD pipelines?

A: Yes, Playwright MCP runs seamlessly in CI/CD environments across Windows, Linux, and macOS. It supports headless mode for efficient background operations.