{"id":11564,"library":"playwright-mcp-server","title":"Playwright MCP Server","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","playwright","testing","mcp","cursor","automation","typescript"],"install":[{"cmd":"npm install playwright-mcp-server","lang":"bash","label":"npm"},{"cmd":"yarn add playwright-mcp-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add playwright-mcp-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for browser automation to capture context and execute tests.","package":"playwright","optional":false},{"reason":"Required for AI model interactions to generate test code from prompts.","package":"openai","optional":false}],"imports":[{"note":"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.","symbol":"SiteContext","correct":"import type { SiteContext } from 'playwright-mcp-server'"},{"note":"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`).","symbol":"AuthConfiguration","correct":"import type { AuthConfiguration } from 'playwright-mcp-server'"},{"note":"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.","symbol":"McpServerConfig","correct":"import type { McpServerConfig } from 'playwright-mcp-server'"}],"quickstart":{"code":"/* quickstart.ts: Setup and Configuration for Playwright MCP Server */\n\n// 1. Ensure your OpenAI API Key is set as an environment variable.\n// This is crucial for the server to generate tests using AI models.\n// Example (run in your shell or .env file):\n// export OPENAI_API_KEY=\"sk-your-actual-api-key\"\n\n// For demonstration purposes in a script, you might access it like:\nconst openaiApiKey = process.env.OPENAI_API_KEY ?? '';\n\nif (!openaiApiKey) {\n  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.\");\n}\n\nconsole.log(\"\\n2. Install dependencies for the Playwright MCP Server:\");\nconsole.log(\"   $ npm install\");\n\nconsole.log(\"\\n3. Start the Playwright MCP Server (typically in a separate terminal):\");\nconsole.log(\"   $ npm start\");\nconsole.log(\"   (or using npx if globally available: $ npx playwright-mcp-server)\");\n\nconsole.log(\"\\n4. Configure Cursor IDE to use this MCP server. Create or update your project's `.cursor/settings.json` file:\");\nconsole.log(JSON.stringify({\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"playwright-mcp-server\"\n      ]\n    }\n  }\n}, null, 2));\n\nconsole.log(\"\\nOnce the server is running and Cursor is configured, you can interact with it via Cursor's chat interface, e.g.:\");\nconsole.log(\"   /mcp playwright Create a test on the login page that validates user authentication.\");\n\n// Note: This TypeScript quickstart primarily outlines the setup and command execution,\n// as the package is a server rather than a library for direct programmatic import.","lang":"typescript","description":"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."},"warnings":[{"fix":"Set `export OPENAI_API_KEY=\"your-key-here\"` in your shell or `.env` file before starting the server.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review `.playwright-mcp-auth.json` for correct `username`, `password`, `loginUrl`, and selector values (`usernameSelector`, `passwordSelector`, `submitSelector`). Ensure `requiresLogin` patterns accurately match protected routes.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The required `OPENAI_API_KEY` environment variable is missing from the server's environment.","error":"ERROR: OPENAI_API_KEY environment variable is not set."},{"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`.","cause":"The `playwright-mcp-server` package is not installed or the `npx` command cannot resolve its location.","error":"Error: Cannot find module 'playwright-mcp-server'"},{"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.","cause":"The `site-context.json` file, which defines your site's structure, is missing or located in an unexpected path.","error":"Error: ENOENT: no such file or directory, stat '/path/to/project/site-context.json'"},{"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.","cause":"The authentication configuration in `.playwright-mcp-auth.json` is incorrect, preventing successful login to protected pages.","error":"Failed to authenticate. Check username, password, or selectors in .playwright-mcp-auth.json"},{"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.","cause":"Cursor IDE could not start or establish a connection with the configured MCP server process.","error":"MCP server 'playwright' not found or failed to start."}],"ecosystem":"npm"}