simple-playwright-mcp

Simple Playwright MCP Server

A powerful Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. This server enables AI assistants like Claude/Cursor/ChatGPT to interact with web pages, extract content, take screenshots, and execute custom browser automation scripts.

This package minimizes the amount of tools to help AI Agents pick the right tool for a given prompt.

Features

• 🌐 Multi-Browser Support - Chromium, Firefox, and WebKit
• 🔄 Session Management - Persistent browser sessions for multi-step workflows
• 📸 Screenshot Capture - Full-page and element-specific screenshots
• 📝 Content Extraction - Text content from pages or specific selectors
• 🖱️ Element Interaction - Click elements and interact with pages
• 🎭 Custom Scripts - Execute arbitrary Playwright code
• 🚀 Dual Transport - HTTP and stdio (for Claude Code)

For detailed information about available tools, see tools.md.

Table of Contents

• Simple Playwright MCP Server
  • Features
  • Table of Contents
  • Getting Started
    • Prerequisites
  • Configuration
    • Environment Variables
    • Cursor / Claude Code / Claude Desktop Configuration
    • HTTP Transport (for n8n or other HTTP clients)
  • Development
    • Development Scripts
  • Troubleshooting
    • Common Issues
    • Debug Logging
  • Contributing
  • License
  • Acknowledgments

Getting Started

Prerequisites

• Node.js 18 or higher
• npm or yarn

Configuration

Environment Variables

Configure the server behavior using environment variables:

Variable	Description	Default	Options
PLAYWRIGHT_HEADLESS	Run browser in headless mode	true	true, false
BROWSER_TYPE	Browser engine to use	chromium	chromium, firefox, webkit
SCREENSHOT_DIR	Directory for saving screenshots	./screenshots	Any valid path
PORT	HTTP server port	4201	Any valid port number
MCP_AUTH_TOKEN	Authentication token for HTTP server (optional)	None	Any string
RETURN_SCREENSHOTS	Return base64 screenshot data to agent	false	true, false

Cursor / Claude Code / Claude Desktop Configuration

To use this server with Cursor/Claude Code/Claude Desktop, add it to your MCP settings file.

Configuration:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "simple-playwright-mcp"
      ],
      "env": {
        "PLAYWRIGHT_HEADLESS": "false",
        "BROWSER_TYPE": "chromium",
        "SCREENSHOT_DIR": "/Users/yourname/projects/playwright-mcp/screenshots",
        "RETURN_SCREENSHOTS": "false"
      }
    }
  }
}

Note: After updating the configuration, restart Claude Code/Desktop for changes to take effect.

HTTP Transport (for n8n or other HTTP clients)

Start the HTTP server:

npm install
npm start
# or with custom port
PORT=4201 npm start

# With authentication (recommended)
MCP_AUTH_TOKEN=your-secret-token npm start

The server will listen on http://localhost:4201/mcp (or your custom port).

Authentication (Optional):

You can secure the HTTP server with token-based authentication by setting the MCP_AUTH_TOKEN environment variable. If set, all requests must include the token in the Authorization header.

Example HTTP Request (with authentication):

curl -X POST http://localhost:4201/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "navigate",
      "arguments": {
        "url": "https://example.com"
      }
    }
  }'

Development

Development Scripts

npm install

# Start HTTP server with auto-reload
npm run dev

# Start stdio server with auto-reload
npm run dev:stdio

# Build TypeScript to JavaScript
npm run build

# Install Playwright browsers
npm run install-browsers

Troubleshooting

Common Issues

1. Node.js version too old

Error: Playwright requires Node.js 18 or higher

Solution: Update Node.js to version 18 or higher.

2. Browser not installed

Error: Executable doesn't exist at /path/to/browser

Solution: Run npm run install-browsers

3. Permission denied (Claude Code)

Error: EACCES: permission denied

Solution: Ensure the script has execute permissions and use absolute paths in configuration.

4. Port already in use (HTTP mode)

Error: listen EADDRINUSE: address already in use :::4201

Solution: Change the port with PORT=4201 npm start

Debug Logging

For stdio mode, logs are written to stderr and appear in Claude Code logs:

• macOS: ~/Library/Logs/Claude/mcp-server-playwright.log
• Linux: ~/.config/Claude/logs/mcp-server-playwright.log

For HTTP mode, logs appear in the terminal where you started the server.

Contributing

Contributions are welcome! Please:

• Fork the repository
• Create a feature branch
• Make your changes
• Run npm run build to ensure it compiles
• Test your changes
• Submit a pull request

License

MIT

Acknowledgments

Built with:

• Playwright - Browser automation
• Model Context Protocol SDK - MCP implementation
• Zod - Schema validation
• Express - HTTP server (for n8n mode)