Registry / testing / playwright-mcp-server

playwright-mcp-server

library0.1.0jsnpmunverified

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.

testing

npm install playwright-mcp-server

package ↗

INSTALL

IMPORT

SIG · PLAYWRIGHT-MCP-SER

playwright-mcp-server

testingjavascriptv0.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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.

Debug

Known issues

gotchaThe 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaAuthentication 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.

affects: >=1.0.0

gotchaProper 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.

affects: >=1.0.0

gotchaThis 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.

affects: >=1.0.0

Errors

Common errors & fixes

ERROR: OPENAI_API_KEY environment variable is not set.

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'

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'

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

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.

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.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

playwrightrequiredUsed for browser automation to capture context and execute tests.

openairequiredRequired for AI model interactions to generate test code from prompts.

Agent activity

4 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/playwright-mcp-server ↗