playwright-ui-mcp

A lightweight MCP (Model Context Protocol) server for headed browser UI capture and analysis using Playwright. Designed for use with Claude to enable visual UI inspection, screenshots, and browser automation.

Features

• Headed browser - Always visible, not headless, for real UI analysis
• Lightweight by default - No video recording unless explicitly enabled
• Screenshot capture - Returns base64 images for Claude to analyze
• Video recording - Optional, enable only when needed
• Auto cleanup - All screenshots/videos deleted when browser closes
• Interactive elements - Get clickable elements with selectors

Installation

Automatic Install (Recommended)

Install as a dependency in your project. The configuration (.mcp.json) is created automatically.

npm install playwright-ui-mcp

Quick Setup (Without Installing)

If you just want to configure the current directory without adding a dependency:

npx playwright-ui-mcp-install

Manual Configuration

Create .mcp.json in your project root:

{
  "mcpServers": {
    "playwright-ui": {
      "command": "npx",
      "args": ["-y", "playwright-ui-mcp"]
    }
  }
}

Then restart Claude Code or run /mcp to load the server.

Available Tools

| Tool | Description | |------|-------------| | browser_launch | Launch headed browser. Options: width, height, slowMo, recordVideo | | browser_new_page | Create a new tab | | browser_navigate | Navigate to URL | | browser_screenshot | Capture screenshot (returns base64 image for analysis) | | browser_get_visible_elements | Get interactive elements with selectors | | browser_get_content | Get page HTML and text | | browser_click | Click an element | | browser_type | Type into input field | | browser_wait_for | Wait for element to appear | | browser_evaluate | Run JavaScript in page | | browser_close_page | Close a specific tab | | browser_close | Close browser and cleanup all captures | | browser_status | Get session info |

Usage Examples

Basic UI Inspection

Ask Claude:

"Open a browser, go to https://example.com, and describe what you see"

Claude will:

1. Launch browser
2. Navigate to the URL
3. Take a screenshot
4. Analyze the UI visually
5. Close browser (auto-cleanup)

Form Interaction

"Go to the login page, fill in username '[email protected]' and password 'secret', then click submit"

With Video Recording (Heavy Mode)

"Record a video while you navigate through the checkout flow"

Claude will use recordVideo: true when launching.

Lightweight vs Heavy Mode

| Mode | Video | slowMo | Use Case | |------|-------|--------|----------| | Default (Light) | Off | None | Quick UI checks | | Heavy | On | 100-200ms | Debugging, demos |

// Lightweight (default)
browser_launch()

// Heavy mode for debugging
browser_launch({ recordVideo: true, slowMo: 150 })

Cleanup

All temporary files (screenshots, videos) are automatically deleted when browser_close is called. No manual cleanup required.

Uninstall

Remove from project:

npx playwright-ui-mcp-install uninstall

Requirements

• Node.js >= 18.0.0
• Chromium browser (auto-installed via Playwright on first run)

License

MIT