Setting Up Playwright Model Context Protocol (MCP) on Your Local Machine

SDET
1

Setting Up Playwright Model Context Protocol (MCP) Locally

This guide provides step-by-step instructions to set up the Playwright Model Context Protocol (MCP) server on your local machine, enabling AI agents to perform browser automation tasks using Playwright.

Introduction

Playwright MCP is a server that facilitates browser automation by allowing Large Language Models (LLMs) to interact with web pages through structured accessibility snapshots. This approach eliminates the need for screenshots or visually-tuned models, making it efficient for automating and extracting web data.

Prerequisites

Ensure the following are installed on your system:

  • Node.js (LTS version recommended)
  • Playwright
  • Playwright MCP
  • A local LLM agent (e.g., Cursor AI or Claude AI)
  • Any BDD feature file

Installation Steps

  1. Install Playwright and MCP

    npm install -g playwright
npm install -g @playwright/mcp@latest

  2. Verify Playwright Installation

    npx playwright --version

  3. Install and Configure an LLM Agent

  4. Configure MCP in Cursor AI

    • Navigate to: Cursor AI Settings → Add New Global MCP Server

    • This will open the mcp.json file. Add the following configuration:

      {
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ],
      "env": {
        "PLAYWRIGHT_WS_ENDPOINT": "ws://localhost:<port>/"
      }
    }
  }
}

  5. Start MCP Server

    npx playwright run-server

    This command starts the MCP server and generates a WebSocket endpoint (ws://localhost:<port>/). Update your mcp.config.json with this port.

  6. Verify MCP in Cursor AI

    • Navigate to: Settings → MCP in Cursor AI
    • Check if it detects the running MCP server

Running BDD Scenarios with MCP

Once the MCP server is running, you can prompt your AI agent to execute test steps from your BDD feature file.

Example Feature File (Login.feature):

Feature: Admin Login
  Scenario: Admin User login with valid credentials
    Given I am in login screen
    When I enter valid email and password
    When I submit the login form
    Then I should see modal for setting up new password

Prompt to AI Agent:

Perform the following actions specified in the Feature file:

The AI agent will interpret the steps and interact with the UI accordingly. It will provide parameters and an accessibility snapshot response of the web application.

Example Response:

  • Parameters:
  {
    "url": "http://localhost:3000"
  }

  • Result:
  - Page URL: http://localhost:3000/
  - Page Title: Admin Web Application
  - Page Snapshot

  - document [ref=s1e2]:
    - paragraph [ref=s1e9]: Welcome to Admin Application
    - paragraph [ref=s1e10]: Your trusted partner for seamless account creation and management.
    - img "login" [ref=s1e12]
    - img "logo" [ref=s1e15]
    - paragraph [ref=s1e16]: Admin Login
    - paragraph [ref=s1e17]: Enter your login credentials to access your account
    - text: Username/Email *
    - textbox "Username/Email * Password*" [ref=s1e22]
    - text: Password*
    - textbox "Enter password" [ref=s1e26]
    - img "show-password" [ref=s1e27]
    - paragraph [ref=s1e28]: Forgot Password?
    - button "Login" [ref=s1e29]

After executing all the Gherkin scenarios, you can prompt the AI agent to provide the corresponding Playwright script, which will be generated as a spec file.

Key Benefits of Using MCP with BDD

  • Reduced Manual Effort: Run feature files without explicitly writing step definitions, as MCP can interpret the steps and interact with the UI.
  • Faster Automation: Eliminates the need to research element locators or write test automation scripts manually. AI handles it dynamically.
  • Flexibility in Execution: Once development is complete, you can directly run the feature file without additional setup.

Troubleshooting

You might encounter a version mismatch issue between your MCP client (e.g., Cursor AI) and the Playwright MCP server.

In such cases, start the Playwright server with a specific version that matches the client version:

npx playwright@1.52.0-alpha-2025-03-21 run-server

You can replace the version (1.52.0-alpha-2025-03-21) with the exact version your client is expecting.

To check the currently installed version of Playwright MCP:

npx playwright --version

Make sure the MCP server and client are using compatible versions to avoid connection issues.

3 Likes