Playwright MCP Server

Playwright MCP Server — POC with 100+ Test Cases

VentureDive QA Engineering Prepared by: Raheel Imran Date: May 2026

---

Overview

This Proof of Concept (POC) demonstrates the Playwright MCP Server (@playwright/mcp) used as the browser automation engine for a complete test suite. It includes:

• A fully functional demo web application — TaskMaster Pro
• 166 Playwright test cases across 8 feature areas using reusable MCP-style commands
• A cmd fixture that maps directly to @playwright/mcp tool names
• A live MCP server demo that connects via @modelcontextprotocol/sdk and drives the browser using real MCP protocol — no external API calls
• MCP server configuration for Claude Desktop and Claude Code
• An interactive HTML test report

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                   Playwright MCP POC                         │
│                                                              │
│  ┌───────────────────┐   MCP Protocol    ┌────────────────┐  │
│  │  MCP Client       │◄─────────────────►│ @playwright/mcp│  │
│  │  (run-demo.ts)    │   stdio transport │  Server        │  │
│  └───────────────────┘                   └───────┬────────┘  │
│                                                  │           │
│                                         Playwright Browser   │
│                                                  │           │
│                                         ┌────────▼─────────┐ │
│                                         │ TaskMaster Pro   │ │
│                                         │ localhost:3000   │ │
│                                         └──────────────────┘ │
│                                                              │
│  Playwright Test Runner (166 tests)                          │
│  └── tests/fixtures/browser-commands.ts  ← reusable cmd      │
│      ├── auth.spec.ts          (25 tests)                    │
│      ├── navigation.spec.ts    (20 tests)                    │
│      ├── dashboard.spec.ts     (12 tests)                    │
│      ├── tasks.spec.ts         (45 tests)                    │
│      ├── categories.spec.ts    (14 tests)                    │
│      ├── profile.spec.ts       (17 tests)                    │
│      ├── settings.spec.ts      (17 tests)                    │
│      └── ui-components.spec.ts (16 tests)                    │
└──────────────────────────────────────────────────────────────┘

---

Quick Start

1. Install dependencies

npm install
npx playwright install chromium

2. Start the demo app

npm run dev
# → http://localhost:3000

3. Run all tests and generate HTML report

npm test
npm run test:report    # opens playwright-report/index.html

4. Run the MCP server demo (browser driven via MCP protocol)

npm run demo
# Starts @playwright/mcp server, connects as MCP client, runs 10 scenarios

5. Interactive test runner

npm run test:ui

---

npm Scripts

| Script | Description | |--------|-------------| | npm run dev | Start the TaskMaster Pro demo app on port 3000 | | npm test | Run all 100+ tests (Chromium + Firefox) | | npm run test:ui | Open Playwright interactive UI mode | | npm run test:report | Open generated HTML report | | npm run test:headed | Run tests in headed browser | | npm run test:debug | Run tests with Playwright debugger | | npm run demo | Run the MCP server demo (real MCP protocol) | | npm run mcp:start | Start @playwright/mcp standalone server |

---

Reusable Browser Commands

All tests import from tests/fixtures/browser-commands.ts instead of @playwright/test directly. Command names match @playwright/mcp tool names exactly, making the test code portable to any MCP client.

import { test, expect } from './fixtures/browser-commands';

test('example', async ({ cmd }) => {
  await cmd.browser_navigate('/login.html');
  await cmd.browser_type('email-input', 'testuser@test.com');
  await cmd.browser_type('password-input', 'Test@123');
  await cmd.browser_click('login-btn');
  await cmd.browser_expect_url(/dashboard/);
  await cmd.browser_take_screenshot('login-success.png');
});

Full command reference

| Command | MCP Tool | Description | |---------|----------|-------------| | cmd.browser_navigate(url) | browser_navigate | Navigate to URL | | cmd.browser_navigate_back() | browser_navigate_back | Go back in history | | cmd.browser_click(testId) | browser_click | Click element by data-testid | | cmd.browser_type(testId, text) | browser_type | Fill input field | | cmd.browser_clear_and_type(testId, text) | browser_type | Clear then fill | | cmd.browser_select_option(testId, value) | browser_select_option | Select dropdown option | | cmd.browser_check(testId) | browser_click | Check a checkbox | | cmd.browser_uncheck(testId) | browser_click | Uncheck a checkbox | | cmd.browser_take_screenshot(filename?) | browser_take_screenshot | Capture screenshot | | cmd.browser_get_url() | — | Get current URL | | cmd.browser_get_text(testId) | — | Get element text | | cmd.browser_get_value(testId) | — | Get input value | | cmd.browser_is_visible(testId) | browser_snapshot | Returns boolean | | cmd.browser_is_checked(testId) | browser_snapshot | Returns boolean | | cmd.browser_count(testId) | browser_snapshot | Count elements | | cmd.browser_wait_for(testId, state?) | browser_wait_for | Wait for element | | cmd.browser_wait_for_url(pattern) | — | Wait for URL | | cmd.browser_set_storage(key, value) | — (fixture-only) | Set localStorage via page.evaluate | | cmd.browser_evaluate(fn) | — (fixture-only) | Run JS via page.evaluate | | cmd.browser_expect_url(pattern) | — | Assert current URL | | cmd.browser_expect_visible(testId) | — | Assert visible | | cmd.browser_expect_hidden(testId) | — | Assert hidden | | cmd.browser_expect_text(testId, text) | — | Assert text content | | cmd.browser_expect_count(testId, n) | — | Assert element count | | cmd.browser_expect_value(testId, val) | — | Assert input value | | cmd.browser_expect_checked(testId) | — | Assert checkbox state | | cmd.browser_expect_disabled(testId) | — | Assert disabled | | cmd.browser_expect_attr(testId, attr, val) | — | Assert attribute |

---

Demo App — TaskMaster Pro

A fully self-contained web app using localStorage for all data persistence.

| Page | URL | Features | |------|-----|----------| | Login | /login.html | Form validation, password toggle, remember-me | | Register | /register.html | Password strength, validation | | Dashboard | /dashboard.html | Stats, recent tasks, quick-add | | Tasks | /tasks.html | CRUD, filter, search, sort, bulk actions | | Categories | /tasks.html#categories | Create, edit, delete categories | | Profile | /profile.html | Edit name, avatar, change password | | Settings | /settings.html | Theme, notifications, language, export | | 404 | /404.html | Error page |

Default test credentials:

| Email | Password | Role | |-------|----------|------| | testuser@test.com | Test@123 | Test User | | admin@test.com | Admin@123 | Admin User |

Pre-seeded data: 5 tasks (3 active, 2 completed) and 4 categories.

MCP Tools provided by @playwright/mcp

See the full categorized reference in MCP Server Setup → Available MCP tools below. Key tools used in this demo app:

| Tool | Description | |------|-------------| | browser_navigate | Navigate to a URL | | browser_snapshot | Get accessibility tree — returns ARIA refs for click/type targets | | browser_click | Click an element by ARIA ref | | browser_type | Type text into a focused field | | browser_fill_form | Fill multiple form fields in one call | | browser_select_option | Select a dropdown value | | browser_take_screenshot | Capture the current page as an image | | browser_localstorage_set | Write a localStorage key (used for fast auth seeding) | | browser_evaluate | Evaluate JavaScript on the page | | browser_wait_for | Wait for an element or condition | | browser_network_requests | Inspect captured network traffic | | browser_route | Mock API responses for isolated testing | | browser_tabs | List, open, close, or switch tabs | | browser_close | Close the browser |

---

MCP Server Setup

@playwright/mcp exposes browser automation as MCP tools so any MCP-compatible client (Claude Code, Claude Desktop, VS Code, Cursor, Windsurf) can drive a real browser with no screenshots or vision models — just accessibility snapshots.

Claude Code (project-level)

A .mcp.json file is included at the project root. Claude Code picks it up automatically when you open this directory:

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

Or install it manually via the CLI:

claude mcp add playwright npx @playwright/mcp@latest

Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

VS Code

One-liner via the VS Code CLI:

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

Or use the included .vscode/mcp.json — VS Code with the Copilot extension picks it up automatically:

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Cursor / Windsurf

Add the same block under mcpServers in their respective settings files.

Configuration options

Append flags to the args array to customise the server:

| Flag | Effect | |------|--------| | --headless | Run browser without a visible window (default: headed) | | --browser <browser> | Browser to use: chrome, firefox, webkit, msedge (default: Chromium) | | --isolated | Keep browser profile in memory; do not persist to disk | | --port <n> | Expose the server over HTTP/SSE instead of stdio | | --host <host> | Host to bind to (default: localhost; use 0.0.0.0 for all interfaces) | | --vision | Use screenshots instead of accessibility snapshots (requires vision model) | | --caps <caps> | Comma-separated capability subset: tabs,pdf,history,wait,files,install | | --device <device> | Emulate a device, e.g. "iPhone 15" | | --viewport-size <size> | Set viewport, e.g. "1280, 720" | | --user-agent <ua> | Override the browser user-agent string | | --storage-state <path> | Load saved auth state (cookies/localStorage) from a JSON file | | --save-trace | Save a Playwright Trace of the session to --output-dir | | --output-dir <path> | Directory for screenshots, PDFs, and traces | | --proxy-server <proxy> | Route traffic through a proxy, e.g. http://myproxy:3128 | | --no-sandbox | Disable the browser sandbox (useful in some CI environments) | | --extension | Connect to an existing browser tab instead of launching a new browser | | --config <path> | Load advanced settings from a JSON config file |

Example — headless Firefox in isolated mode:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--browser=firefox", "--isolated"]
    }
  }
}

Standalone server (HTTP transport)

For headless/CI environments where stdio is not suitable:

npx @playwright/mcp@latest --port 8931

Then point your MCP client at http://localhost:8931/mcp using the url form:

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

Available MCP tools

Navigation

| Tool | Description | |------|-------------| | browser_navigate | Navigate to a URL | | browser_navigate_back / browser_navigate_forward | Browser history navigation | | browser_reload | Reload the current page |

Interaction

| Tool | Description | |------|-------------| | browser_click | Click an element by ARIA ref | | browser_check / browser_uncheck | Check or uncheck a checkbox | | browser_type | Type text into a focused field | | browser_press_sequentially | Type text one character at a time (for masked fields) | | browser_fill_form | Fill multiple form fields by their labels in one call | | browser_select_option | Select a dropdown value | | browser_hover | Hover over an element | | browser_drag / browser_drop | Drag-and-drop between elements | | browser_press_key / browser_keydown / browser_keyup | Keyboard key events | | browser_handle_dialog | Accept or dismiss browser dialogs | | browser_file_upload | Upload a file to a file input | | browser_mouse_click_xy / browser_mouse_move_xy / browser_mouse_drag_xy | Pixel-precise mouse control | | browser_mouse_down / browser_mouse_up / browser_mouse_wheel | Low-level mouse events |

Inspection & Assertions

| Tool | Description | |------|-------------| | browser_snapshot | Get the page accessibility tree — primary way to read elements and obtain ARIA refs | | browser_take_screenshot | Capture the current page as an image | | browser_annotate | Capture a screenshot with annotated highlights | | browser_highlight / browser_hide_highlight | Visually highlight an element on the page | | browser_generate_locator | Generate a Playwright locator for a given element | | browser_verify_element_visible | Assert an element is visible | | browser_verify_text_visible | Assert specific text is visible on the page | | browser_verify_list_visible | Assert a list of items is visible | | browser_verify_value | Assert an element's value | | browser_wait_for | Wait for an element or network condition |

Storage

| Tool | Description | |------|-------------| | browser_evaluate | Evaluate a JavaScript expression on the page | | browser_localstorage_get / browser_localstorage_set / browser_localstorage_list | Read/write localStorage | | browser_localstorage_clear / browser_localstorage_delete | Remove localStorage items | | browser_sessionstorage_get / browser_sessionstorage_set / browser_sessionstorage_list | sessionStorage CRUD | | browser_sessionstorage_clear / browser_sessionstorage_delete | Remove sessionStorage items | | browser_cookie_get / browser_cookie_set / browser_cookie_list | Read/write cookies | | browser_cookie_clear / browser_cookie_delete | Remove cookies | | browser_storage_state | Export current cookies and storage to a file | | browser_set_storage_state | Import previously saved storage state |

Network

| Tool | Description | |------|-------------| | browser_network_requests | List all captured network requests | | browser_network_request | Get details for a single network request | | browser_network_clear | Clear the captured request log | | browser_network_state_set | Simulate online/offline/throttled network conditions | | browser_route | Mock requests matching a URL pattern with a custom response | | browser_route_list | List active route mocks | | browser_unroute | Remove a route mock |

Tabs

| Tool | Description | |------|-------------| | browser_tabs | List, create (new), close, or switch to a tab by index |

Console

| Tool | Description | |------|-------------| | browser_console_messages | Get browser console output | | browser_console_clear | Clear the console message log |

Recording & Tracing

| Tool | Description | |------|-------------| | browser_start_tracing / browser_stop_tracing | Record a Playwright Trace | | browser_start_video / browser_stop_video / browser_video_chapter | Record session video | | browser_pdf_save | Save the current page as a PDF |

Misc

| Tool | Description | |------|-------------| | browser_resize | Resize the browser window | | browser_get_config | Get the current server configuration | | browser_run_code_unsafe | Execute an arbitrary Playwright script (RCE-equivalent; trusted clients only) | | browser_close | Close the browser |

How accessibility snapshots work: Instead of returning a screenshot, browser_snapshot returns a structured text tree of all visible elements with their roles, labels, and unique [ref=…] identifiers. LLMs reference these ids when calling browser_click or browser_type — no vision model required.

Verify the server is working

# Start the demo app first
npm run dev

# Then run the MCP demo (connects via stdio and runs 10 browser scenarios)
npm run demo

---

MCP Demo (demo/)

demo/run-demo.ts connects to @playwright/mcp via real MCP stdio protocol using @modelcontextprotocol/sdk. It runs 10 browser scenarios with no external API dependencies.

npm run demo

╔══════════════════════════════════════════════════════════╗
║  Playwright MCP Server — Direct MCP Protocol Demo       ║
╚══════════════════════════════════════════════════════════╝

Target: http://localhost:3000
Transport: stdio (@playwright/mcp subprocess)

Connecting to @playwright/mcp server…
Connected.

Available MCP tools (14):
  • browser_navigate
  • browser_snapshot
  • browser_click
  …

S01  ✓ PASS  Login page loads via MCP browser_navigate
S02  ✓ PASS  Fill login form using browser_type
S03  ✓ PASS  Capture login page screenshot
…

---

Test Coverage

| Area | Tests | TC Range | |------|-------|----------| | Authentication | 25 | TC001–TC025 | | Navigation | 20 | TC026–TC045 | | Dashboard | 12 | TC046–TC057 | | Task Management | 45 | TC058–TC102 | | Categories | 14 | TC103–TC116 | | Profile | 17 | TC117–TC133 | | Settings | 17 | TC134–TC150 | | UI Components | 16 | TC151–TC166 | | Total | 166 | |

---

Project Structure

.
├── demo-app/
│   ├── server.js                  Express static file server (port 3000)
│   └── public/
│       ├── index.html             Entry point (redirect)
│       ├── login.html
│       ├── register.html
│       ├── dashboard.html
│       ├── tasks.html             Tasks + Categories
│       ├── profile.html
│       ├── settings.html
│       ├── 404.html
│       ├── css/styles.css
│       └── js/utils.js            Shared helpers + seed data
├── tests/
│   ├── fixtures/
│   │   └── browser-commands.ts    Reusable MCP-style command fixture
│   ├── helpers/
│   │   └── auth.helper.ts         Fast localStorage-based auth setup
│   ├── auth.spec.ts               TC001–TC025
│   ├── navigation.spec.ts         TC026–TC045
│   ├── dashboard.spec.ts          TC046–TC057
│   ├── tasks.spec.ts              TC058–TC102
│   ├── categories.spec.ts         TC103–TC116
│   ├── profile.spec.ts            TC117–TC133
│   ├── settings.spec.ts           TC134–TC150
│   └── ui-components.spec.ts      TC151–TC166
├── demo/
│   ├── scenarios.ts               10 MCP test scenario definitions
│   └── run-demo.ts                MCP client demo (real MCP protocol)
├── playwright-report/             Generated HTML report (after npm test)
├── playwright.config.ts
├── package.json
└── tsconfig.json

---

Key Design Decisions

| Decision | Rationale | |----------|-----------| | data-testid attributes on all elements | Tests don't break when CSS or text changes | | Reusable browser-commands.ts fixture | Command names match @playwright/mcp tools — tests are portable | | loginViaStorage() helper | Sets session via localStorage.setItem directly — 10× faster than UI login | | Sequential workers (workers: 1) | Prevents localStorage conflicts between parallel tests | | retries: 1 locally, retries: 2 on CI | Handles transient timing issues without masking real failures | | No external API dependencies | MCP demo uses @playwright/mcp directly via stdio protocol |

---