Playwright Test Agent MCP Server

Run, generate, and debug Playwright tests through Claude or any MCP-compatible client. Manage your test suites with natural language — no terminal required.

Quick Start

Claude Desktop

Add to your Claude Desktop MCP config:

{
  "mcpServers": {
    "playwright-test-agent": {
      "url": "https://your-apify-actor-url/runs/standby"
    }
  }
}

Local Development

git clone <repo>
cd playwright-test-agent
pip install -r requirements.txt
npm install @playwright/test
npx playwright install chromium
python src/server.py

Configuration

Parameter	Description	Required	Default
PROJECT_PATH	Path to Playwright project (where playwright.config.ts lives)	No	Current directory
OPENAI_API_KEY	API key for LLM features (test generation, failure debugging)	No	—
OPENAI_BASE_URL	OpenAI-compatible API base URL	No	https://api.openai.com/v1
OPENAI_MODEL	LLM model for test generation and debugging	No	gpt-4o

Available Tools

run_test_file

Execute a Playwright test spec and get structured results.

• Parameters: test_file (str, required), project (str, optional — browser project name)
• Returns: Test results with pass/fail status, duration, and failure details per test

generate_test

Generate a Playwright test from a natural language description.

• Parameters: description (str, required), base_url (str, optional)
• Returns: Generated Playwright TypeScript test code

get_test_results

Retrieve results from the last Playwright test run.

• Parameters: results_dir (str, optional)
• Returns: Summary of last run with pass/fail counts and failure details

debug_failure

Analyze a test failure and get fix suggestions.

• Parameters: test_file (str, required), failure_message (str, required), screenshot_path (str, optional)
• Returns: Analysis with root cause and suggested fixes

list_test_files

List all Playwright spec files in the project.

• Parameters: test_dir (str, optional)
• Returns: Array of spec file paths with last modified timestamps

Example Prompts

1. "Run the login test suite and show me the results"
2. "Generate a Playwright test that verifies the checkout flow on my e-commerce site"
3. "What were the results of my last test run?"
4. "Debug this test failure: 'Timeout waiting for selector .submit-btn'"
5. "List all test files in my project"

Pricing

Plan	Price	Includes
Monthly	$29/mo	Unlimited test runs, LLM-powered test generation, failure debugging

Local Development

# Install Python dependencies
pip install -r requirements.txt

# Install Playwright
npm install @playwright/test
npx playwright install chromium

# Set project path (optional)
export PROJECT_PATH=/path/to/your/playwright/project

# For LLM features (optional)
export OPENAI_API_KEY=your-key

# Run the server
python src/server.py

Troubleshooting

• "npx not found": Ensure Node.js is installed and npx is in PATH
• Browser not installed: Run npx playwright install chromium
• Test generation not working: Verify OPENAI_API_KEY is set
• Timeout errors: Increase the Playwright timeout in your playwright.config.ts
• Permission denied: Ensure the server has read access to the test directory