🎭 Local Playwright Project Control via LLM

A custom MCP (Model Context Protocol) server designed for local Playwright project control through LLM interactions.

Unlike global Playwright MCP installations, this project enables intelligent automation and management of specific Playwright projects within your local development environment.

🎯 Purpose and Scope

This is not a global Playwright MCP server. Instead, it's a specialized MCP implementation that:

✅ Controls local Playwright projects through natural language interactions
✅ Manages project-specific testing workflows intelligently
✅ Provides context-aware automation for your development environment
✅ Integrates seamlessly with existing Playwright projects without global installation requirements

🔄 Comparison with Copilot/Cursor

This local Playwright MCP approach offers distinct advantages over traditional AI coding assistants.

Traditional AI Assistants (Copilot/Cursor)

How they work:

Provide code suggestions and completions within your editor
Generate code snippets based on comments or context
Require manual execution of generated commands
Work primarily at the file/code level

Limitations:

❌ No execution capability - They suggest code but can't run it
❌ Editor-bound - Limited to the specific IDE/editor environment
❌ Manual workflow - You must copy, paste, and execute suggested commands
❌ Context switching - Need to switch between AI suggestions and terminal/testing tools
❌ Generic responses - Not aware of your specific project structure and testing patterns

This Local Playwright MCP Approach

How it works:

✅ Direct execution - Actually runs tests, manages git operations, and performs project tasks
✅ Conversational control - Natural language commands that immediately execute
✅ Project awareness - Understands your specific project structure, test patterns, and configurations
✅ Workflow integration - Seamlessly combines multiple operations (search → test → commit → push)

Feature Comparison

Feature	Copilot/Cursor	This MCP Approach
Code Execution	❌ Suggests only	✅ Actually executes
Project Context	❌ File-level only	✅ Full project awareness
Workflow Integration	❌ Manual steps	✅ Automated workflows
Natural Language Control	❌ Comment-based	✅ Conversational
Testing Operations	❌ Code generation	✅ Live test execution
Git Integration	❌ Suggests commands	✅ Performs git operations
Multi-step Tasks	❌ Requires manual coordination	✅ Intelligent task chaining
Environment Awareness	❌ Generic	✅ Project-specific

Practical Example Comparison

With Copilot/Cursor:

1. Ask: "How do I run my login tests?"
2. Get code suggestion: `npx playwright test login.spec.ts`
3. Copy the command
4. Switch to terminal
5. Paste and execute
6. Manually interpret results
7. Repeat for any follow-up actions

With This MCP:

1. Say: "Run my login tests and show me the results"
2. ✅ Tests execute automatically
3. ✅ Results are analyzed and presented
4. ✅ Ready for follow-up: "Stage the test files and commit them"
5. ✅ Git operations happen automatically

🎯 When to Use Each Approach

Use Copilot/Cursor when:

Writing new code or functions
Need code suggestions while typing
Working on general programming tasks
Want autocomplete and code generation

Use This MCP when:

Managing existing Playwright projects
Need to execute testing workflows
Want conversational project control
Require integrated git operations
Need project-aware automation
Want to chain multiple development tasks

🤝 Complementary Usage

These approaches can work together:

Copilot/Cursor for writing and generating test code
This MCP for running, managing, and orchestrating those tests
Combined workflow: Generate tests with AI assistants, then control and execute them through natural language with this MCP

🔌 What is MCP (Model Context Protocol)?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. This implementation specifically focuses on local Playwright project management rather than general-purpose web automation.

✨ Local Project Control Features

🧪 Intelligent Test Management

Dynamic test discovery - Automatically find and analyze tests in your project
Context-aware execution - Run tests based on project state and requirements
Smart test filtering - Execute specific test suites based on natural language descriptions
Result analysis - Interpret and explain test outcomes
Self-healing tests - Automatic retry with trace/debug on failures

⚙️ Project-Specific Automation

Local file operations - Work within your project's directory structure
Configuration management - Modify Playwright configs based on requirements
Dependency handling - Manage project dependencies intelligently
Development workflow integration - Seamlessly integrate with existing processes
Custom reporters - Run tests with various output formats (list, dot, json, junit, html)

🤖 LLM-Driven Operations

Natural language commands - Control your Playwright project through conversation
Context understanding - Maintains awareness of your project structure and history
Intelligent suggestions - Provides recommendations based on project analysis
Adaptive responses - Adjusts behavior based on project-specific needs

💻 MCP-Compatible Applications

Claude Desktop

Claude Desktop is the primary application supporting this local MCP implementation:

Connect to your specific Playwright project
Control local testing workflows through conversation
Access project files and configurations
Manage development tasks intelligently

⚙️ Configuration for Local Project Control

Configuration File Location

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Local Playwright Project Configuration

{
  "mcpServers": {
    "local-playwright-control": {
      "command": "/opt/homebrew/opt/node@22/bin/npx",
      "args": [
        "ts-node",
        "--esm",
        "/path/to/your/playwright/repo/index.ts"
      ],
      "cwd": "/path/to/your/playwright/repo"
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/playwright/project"
      ],
      "env": {
        "MCP_FILESYSTEM_READ_ONLY": "false"
      }
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github", "--transport=stdio"],
      "env": {
        "GITHUB_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

📝 Key Configuration Notes

Local Playwright Control

Purpose: Controls your specific Playwright project, not global operations
Scope: Limited to your designated project directories
Intelligence: Understands your project structure and testing patterns
Customization: Adapts to your specific project needs and conventions

Filesystem Access

Project-focused directories: Only accesses your Playwright project and related folders
Contextual awareness: Understands relationships between project files
Safe operations: Limited scope prevents accidental global changes
Development-friendly: Integrates with your existing project structure

🎨 Local Project Control Capabilities

Available Operations

🔍 Project Analysis: Understand test structure and dependencies
🧪 Intelligent Test Execution: Run tests based on contextual requirements
💻 Code Generation: Create tests and page objects suited to your project
⚙️ Configuration Management: Modify project settings intelligently
🐛 Debugging Assistance: Help identify and resolve project-specific issues
📊 Workflow Optimization: Suggest improvements based on project analysis
🔄 Self-Healing Tests: Automatically retry failed tests with trace and debug information

Smart Project Understanding

Test Pattern Recognition: Identifies your testing patterns and conventions
Dependency Mapping: Understands relationships between project components
Configuration Analysis: Reads and interprets your Playwright configuration
File Structure Awareness: Navigates your project intelligently
History Tracking: Remembers previous operations and contexts

🚀 Getting Started with Local Control

Prerequisites

✅ Existing Playwright project
✅ Node.js 16 or higher
✅ Claude Desktop application
✅ This MCP server repository

Setup Steps

1. Configure for Your Project

Update MCP configuration with your project paths
Ensure filesystem access includes your Playwright project directory
Set working directory to this MCP server location

2. Connect Claude Desktop

Add the configuration JSON with your specific paths
Restart Claude Desktop
Verify connection to your local project

3. Start Local Control

Open Claude Desktop
Begin conversation about your Playwright project
Use natural language to describe testing needs
Let the MCP server intelligently manage your project

🎁 Advantages of Local Project Control

vs. Global Playwright MCP

✅ Project-specific context instead of generic web automation
✅ Intelligent project understanding rather than basic command execution
✅ Safe, scoped operations within your designated project boundaries
✅ Development workflow integration tailored to your specific needs

Enhanced Development Experience

✅ Natural language project control through conversational interface
✅ Context-aware automation that understands your project's unique characteristics
✅ Intelligent suggestions based on project analysis and patterns
✅ Seamless integration with existing development tools and workflows

📂 Project Structure

playwright-mcp-local/
├── index.ts           # Main MCP server implementation
├── package.json       # Dependencies and configuration
├── README.md          # This documentation
└── .git/             # Version control

This MCP server acts as an intelligent bridge between your natural language requests and your local Playwright project, enabling sophisticated project control through conversational interaction.

💬 Available LLM Commands

Once configured, you can control your Playwright project using natural language commands through Claude Desktop. Here are the available operations:

🎭 Playwright Project Management

Initialize Playwright Project

Initialize a new Playwright project with TypeScript
Set up Playwright with JavaScript support

Test Discovery and Execution

List all available tests in the project
Show me what tests are available
Run the login test
Execute the user registration test suite
Run tests for changed files only
Run tests with HTML reporter
Run tests with custom reporter and filter by grep pattern

Advanced Test Execution

Run the login test with self-healing (auto-retry with trace on failure)
Execute tests with JSON reporter
Run tests using 4 parallel workers
Filter and run tests matching "authentication" pattern

Project Analysis

Search for "login" in all project files
Find all references to "user authentication"
Show me where "playwright.config" is mentioned

🔧 Git Integration Commands

Repository Management

Initialize git repository
Show current git status
Check which branch I'm on
Show recent commit history
Display git configuration

File Operations

Stage the test file for commit
Add package.json to git
Restore the staged config file
Remove outdated-test.spec.ts from git tracking

Branch and Commit Operations

Create a new branch called "feature-login-tests"
Switch to the main branch
Commit staged files with message "Add new login tests"
Push current branch to origin

Stash Management

Stash current changes
Apply the most recent stash
Show git configuration

Code Analysis and History

Show diff for all changes in working directory
Show diff for specific file: tests/login.spec.ts
Show git blame for the authentication file
View who last modified each line in the test file

🚀 Advanced Workflow Examples

Test Development Workflow

Search for "login" tests, then run them
List all tests, run the ones related to authentication
Show me which files changed, then run tests for those files
Run the checkout test with self-healing enabled

Project Setup and Maintenance

Initialize Playwright with TypeScript, then show available tests
Check git status, stage all test files, and commit with message "Update test suite"
Create a new branch "fix-failing-tests", run all tests, then show results
Run tests with HTML reporter and open the report

Code Investigation

Search for "page.click" usage across the project
Find all test files that use "expect"
Show me where configuration files are mentioned
Show me the diff for the config file
Check who last modified the failing test

Debug and Analysis Workflow

Run the problematic test with self-healing to capture traces
Show me the diff between current and last commit
Check git blame for the file causing issues
Run tests with JUnit reporter for CI integration

💡 Natural Language Flexibility

The MCP server understands natural language, so you can phrase commands conversationally:

Playwright Test Commands:

"Initialize a new Playwright project with TypeScript" → init-playwright
"List all available tests in the project" → list-tests
"Can you run the login test for me?" → run-test
"Run tests only for the files I've recently modified" → run-tests-changed
"Execute tests with HTML reporter" → run-tests-report
"If the test fails, automatically retry it with trace enabled" → run-test-selfheal

Search Commands:

"Search for 'authentication' in all project files" → search-text-in-file
"Find where navigation logic is implemented" → search-text-in-file

Git Repository Commands:

"Initialize a new git repository" → git-init
"Show me the current state of my git repository" → git-status
"Which branch am I currently on?" → git-branch
"Show me the recent commit history" → git-log
"Display my git configuration" → git-config

Git File Management:

"Stage my test files for commit" → git-add
"Unstage the config file" → git-restore
"Remove this file from git tracking" → git-remove

Git Branching and Commits:

"Create a new branch called feature-login" → git-checkout-new
"Switch to the main branch" → git-checkout
"Commit staged files with message 'Add tests'" → git-commit
"Push my changes to origin" → git-push

Git Stash Operations:

"Stash my current changes" → git-stash
"Apply the most recent stash" → git-stash-pop

Git Code Analysis:

"What changes did I make to the config file?" → git-diff
"Show me who last changed this test file" → git-blame
"Show diff for all my working directory changes" → git-diff

📊 Command Categories Summary

Category	Available Operations
🎭 Playwright	`init-playwright`, `list-tests`, `run-test`, `run-tests-changed`, `run-tests-report`, `run-test-selfheal`
🔍 Search	`search-text-in-file` (find text across all project files)
📦 Git Basics	`git-init`, `git-status`, `git-branch`, `git-log`, `git-config`
📁 File Management	`git-add`, `git-restore`, `git-remove`
🌿 Branching	`git-checkout`, `git-checkout-new`, `git-push`
💾 Version Control	`git-commit`, `git-stash`, `git-stash-pop`
🔍 Code Analysis	`git-diff`, `git-blame`

🔧 Tool Details

Playwright Tools

init-playwright - Initialize new Playwright project with TypeScript or JavaScript
list-tests - Discover and list all tests in the project
run-test - Execute a specific test by name
run-tests-changed - Run tests only for files that have changed
run-tests-report - Run tests with custom reporters (list, dot, json, junit, html)
run-test-selfheal - Run test with automatic retry using trace/debug on failure

Git Tools

git-init - Initialize a new Git repository
git-status - Show working tree status
git-branch - List, create, or delete branches
git-add - Stage files for commit
git-restore - Unstage files
git-remove - Remove files from Git tracking
git-commit - Record changes to the repository
git-push - Update remote refs
git-checkout - Switch branches
git-checkout-new - Create and switch to new branch
git-stash - Stash changes in working directory
git-stash-pop - Apply stashed changes
git-log - Show commit logs
git-config - Get and set repository options
git-diff - Show changes between commits, commit and working tree, etc
git-blame - Show what revision and author last modified each line of a file

All commands work within the context of your local Playwright project, providing intelligent automation while maintaining full control over your development environment.

📄 License

This project is open source and available under the MIT License.

Made with ❤️ for local Playwright project control

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
README.md		README.md
index.ts		index.ts
package.json		package.json

sauravthetester/playwright-mcp-local

Folders and files

Latest commit

History

Repository files navigation