Playwright MCP Server

1.0.0 · active · verified Sun Apr 19

The Playwright MCP Server provides an integration with Cursor IDE to enable AI-powered generation of Playwright tests. Operating as a custom Model Context Protocol (MCP) server, it analyzes a project's site context, existing test patterns, and authentication configurations to generate new tests based on user prompts. The server is currently at version 1.0.0, suggesting its initial stable release. Its release cadence is not explicitly stated but is likely tied to its primary use case with the Cursor IDE. Key differentiators include its deep integration with Cursor's chat interface, intelligent code reuse from existing tests, and sophisticated project structure analysis to ensure generated tests adhere to established conventions, making it a specialized tool for accelerating Playwright test development within the Cursor ecosystem.

Common errors

```
ERROR: OPENAI_API_KEY environment variable is not set.
```
cause The required `OPENAI_API_KEY` environment variable is missing from the server's environment.

fix Set the environment variable: `export OPENAI_API_KEY="your-key-here"` in your terminal or ensure it's loaded via an `.env` file when starting the server.
```
Error: Cannot find module 'playwright-mcp-server'
```
cause The `playwright-mcp-server` package is not installed or the `npx` command cannot resolve its location.

fix Run `npm install` in the package's directory. If using `npx`, ensure the package is globally linked (`npm link`) or specify the full path to `src/index.js` in `.cursor/settings.json`.
```
Error: ENOENT: no such file or directory, stat '/path/to/project/site-context.json'
```
cause The `site-context.json` file, which defines your site's structure, is missing or located in an unexpected path.

fix Create `site-context.json` in one of the specified locations (e.g., project root) and ensure it's correctly formatted according to the schema.
```
Failed to authenticate. Check username, password, or selectors in .playwright-mcp-auth.json
```
cause The authentication configuration in `.playwright-mcp-auth.json` is incorrect, preventing successful login to protected pages.

fix Review `.playwright-mcp-auth.json` for correct `username`, `password`, `loginUrl`, and selector values (`usernameSelector`, `passwordSelector`, `submitSelector`). Ensure they match your site's login form.
```
MCP server 'playwright' not found or failed to start.
```
cause Cursor IDE could not start or establish a connection with the configured MCP server process.

fix Verify the `mcpServers` configuration for the `playwright` entry in `.cursor/settings.json`. Check the `command` and `args` paths. Ensure the `playwright-mcp-server` is runnable from your terminal and check its console logs for any startup errors.

Warnings

gotcha The server requires an `OPENAI_API_KEY` environment variable to function. Failure to set this will prevent the AI test generation functionality from working, leading to errors or non-responsive behavior.
Fix: Set `export OPENAI_API_KEY="your-key-here"` in your shell or `.env` file before starting the server.
gotcha The `site-context.json` file is crucial for the server to understand your website structure. Incorrect paths or malformed JSON will lead to the server failing to identify pages or elements correctly.
Fix: Ensure `site-context.json` is correctly formatted and placed in one of the expected locations (project root, `data/`, `config/`, `playwright-mcp-system/`). Validate its JSON structure using a linter.
gotcha Authentication configuration in `.playwright-mcp-auth.json` is critical for testing pages behind a login. Misconfigurations, incorrect selectors, or invalid credentials will result in authentication failures during test generation.
Fix: Review `.playwright-mcp-auth.json` for correct `username`, `password`, `loginUrl`, and selector values (`usernameSelector`, `passwordSelector`, `submitSelector`). Ensure `requiresLogin` patterns accurately match protected routes.
gotcha Proper configuration of `.cursor/settings.json` is essential for Cursor to locate and communicate with the MCP server. Incorrect `command` or `args` paths will prevent Cursor from invoking the server.
Fix: Double-check the `command` (e.g., `npx` or `node`) and `args` (e.g., `playwright-mcp-server` or `/path/to/src/index.js`) in `.cursor/settings.json`. If using `npm link`, `npx` is generally reliable.
gotcha This package is designed as a standalone server, primarily interacted with via the command line and integrated through the Cursor IDE. Attempting to import and use its runtime components programmatically as a library is not its intended use case and may lead to unexpected behavior.
Fix: Operate the `playwright-mcp-server` as a background process and configure your Cursor IDE as instructed in the README, rather than attempting direct programmatic imports of its core server logic.

Install

npm install playwright-mcp-server npm
yarn add playwright-mcp-server yarn
pnpm add playwright-mcp-server pnpm

Imports

SiteContext
```
import type { SiteContext } from 'playwright-mcp-server'
```
This package is primarily a CLI server. Runtime functionality is not typically imported for programmatic use. Types like `SiteContext` may be imported for schema validation or custom tooling, but direct programmatic use of the server's core logic via `import` is not its intended primary interaction pattern.
AuthConfiguration
```
import type { AuthConfiguration } from 'playwright-mcp-server'
```
Similar to `SiteContext`, `AuthConfiguration` is a type definition. Developers typically interact with the server by running it as a process, not by importing its components into their own JavaScript/TypeScript codebases. This type helps define the structure of the authentication configuration file (`.playwright-mcp-auth.json`).
McpServerConfig
```
import type { McpServerConfig } from 'playwright-mcp-server'
```
Represents the configuration shape for the MCP server itself. While the server is run via CLI, its configuration schema might be exported as types for advanced validation or integration. Direct runtime imports are not advised for general usage.

Quickstart

This quickstart demonstrates the essential steps to set up the OpenAI API key, install dependencies, start the Playwright MCP server, and configure the Cursor IDE to interact with it for AI-powered test generation.

/* quickstart.ts: Setup and Configuration for Playwright MCP Server */

// 1. Ensure your OpenAI API Key is set as an environment variable.
// This is crucial for the server to generate tests using AI models.
// Example (run in your shell or .env file):
// export OPENAI_API_KEY="sk-your-actual-api-key"

// For demonstration purposes in a script, you might access it like:
const openaiApiKey = process.env.OPENAI_API_KEY ?? '';

if (!openaiApiKey) {
  console.warn("WARNING: OPENAI_API_KEY environment variable is not set. The MCP server will fail to generate tests.\nPlease set it before starting the server.");
}

console.log("\n2. Install dependencies for the Playwright MCP Server:");
console.log("   $ npm install");

console.log("\n3. Start the Playwright MCP Server (typically in a separate terminal):");
console.log("   $ npm start");
console.log("   (or using npx if globally available: $ npx playwright-mcp-server)");

console.log("\n4. Configure Cursor IDE to use this MCP server. Create or update your project's `.cursor/settings.json` file:");
console.log(JSON.stringify({
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "playwright-mcp-server"
      ]
    }
  }
}, null, 2));

console.log("\nOnce the server is running and Cursor is configured, you can interact with it via Cursor's chat interface, e.g.:");
console.log("   /mcp playwright Create a test on the login page that validates user authentication.");

// Note: This TypeScript quickstart primarily outlines the setup and command execution,
// as the package is a server rather than a library for direct programmatic import.

view raw JSON →