Playwright MCP browser automation for Claude Code

version
0.1.3
GitHub stars
27

Install

/plugin install playwright@vinnie357

Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.

Contents

Discovered from source

Skills 1

Playwright MCP

The Playwright MCP server gives Claude Code agents direct browser control through 50+ tools that operate on the accessibility tree rather than screenshots. This enables fast, structured web interaction — navigating pages, clicking elements, filling forms, extracting content, and taking screenshots — without requiring vision models.

Installation

Claude Code (recommended)

# Default: bunx (preferred)
claude mcp add playwright -- bunx @playwright/mcp@latest

# Fallback: npx
claude mcp add playwright -- npx @playwright/mcp@latest

Verify the MCP server is connected by running /mcp in a Claude Code session.

Runtime Requirement

Bun or Node.js 18+ must be available. Add to your project or global mise.toml:

[tools]
bun = "latest"

See templates/mise.toml for the full template.

Configuration

Global (all sessions)

Add to ~/.claude.json to make Playwright available in every Claude Code session:

{
  "mcpServers": {
    "playwright": {
      "command": "bunx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Per-Project

Add to .mcp.json in the project root for project-scoped configuration:

{
  "mcpServers": {
    "playwright": {
      "command": "bunx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Configuration Flags

Pass flags after the package name in the args array or on the CLI:

claude mcp add playwright -- bunx @playwright/mcp@latest --headless --browser chromium
FlagDefaultDescription
--browserchromeBrowser engine: chrome, firefox, webkit, msedge
--headlessoff (headed)Run without visible browser window
--allowed-originsnoneSemicolon-separated trusted origins
--blocked-originsnoneSemicolon-separated blocked origins
--proxy-servernoneHTTP proxy (e.g., http://proxy:3128)
--viewport-sizebrowser defaultWindow size (e.g., 1280x720)
--devicenoneEmulate device (e.g., iPhone 15)
--timeout-action5000Action timeout in ms
--timeout-navigation60000Navigation timeout in ms
--user-data-dirnonePersistent browser profile path
--isolatedoffUse in-memory profile only
--storage-statenoneLoad saved session state (cookies, localStorage)
--capscore onlyEnable optional capabilities (see below)
--confignonePath to configuration file
--cdp-endpointnoneConnect to existing Chrome DevTools Protocol

All flags support environment variable alternatives (e.g., PLAYWRIGHT_MCP_HEADLESS=true).

Capabilities

The MCP server provides core tools by default. Enable additional capabilities with --caps:

claude mcp add playwright -- bunx @playwright/mcp@latest --caps "network,vision,pdf,testing"
CapabilityFlagDescription
Corealways onNavigation, clicking, typing, snapshots, screenshots, tabs, dialogs
NetworknetworkMonitor requests, set up routes, intercept traffic
StoragestorageCookie/localStorage/sessionStorage CRUD, save/restore state
DevToolsdevtoolsTracing, video recording, console access
VisionvisionCoordinate-based mouse interaction (click/move/drag by x,y)
PDFpdfSave pages as PDF files
TestingtestingLocator generation, element/text/value assertions

JSON Configuration with Capabilities

{
  "mcpServers": {
    "playwright": {
      "command": "bunx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--caps",
        "network,vision,pdf,testing"
      ]
    }
  }
}

Common Use Cases

Web Research

Navigate to a URL and extract content when curl or fetch would be blocked:

Use browser_navigate to go to the URL, then browser_snapshot to read the page content.

Screenshot Capture

Take screenshots of web applications or local dev servers:

Use browser_navigate to the target URL, then browser_take_screenshot to capture the page.
For local dev servers, navigate to http://localhost:<port>.

Form Automation

Automate login flows, data entry, or form submission:

Use browser_snapshot to identify form elements, browser_click to focus inputs,
browser_type to enter values, then browser_click to submit.

Local Dev Testing

Connect to a running local development server for UI verification:

Navigate to http://localhost:3000 (or your dev server port).
Use browser_snapshot to inspect the rendered page structure.
Use testing capability tools for assertions (requires --caps testing).

Tool Categories

Core tools are always available. Optional tools require --caps flags.

CategoryRepresentative ToolsCapability
Navigationbrowser_navigate, browser_navigate_back, browser_navigate_forwardcore
Interactionbrowser_click, browser_type, browser_select_option, browser_hover, browser_dragcore
Inputbrowser_press_key, browser_file_upload, browser_handle_dialogcore
Inspectionbrowser_snapshot, browser_take_screenshot, browser_console_messagescore
JavaScriptbrowser_evaluatecore
Tabsbrowser_tab_new, browser_tab_list, browser_tab_select, browser_tab_closecore
Pagebrowser_resize, browser_wait_for, browser_closecore
Networkbrowser_network_requests, browser_route, browser_unroutenetwork
Storagecookie/localStorage/sessionStorage CRUD, browser_storage_statestorage
DevToolsbrowser_start_tracing, browser_stop_tracing, browser_start_video, browser_stop_videodevtools
Visionbrowser_mouse_click_xy, browser_mouse_move_xy, browser_mouse_drag_xyvision
PDFbrowser_pdf_savepdf
Testingbrowser_generate_locator, browser_verify_element_visible, browser_verify_text_visibletesting

For the full tool catalog with parameters and descriptions, see references/tools-reference.md.

Troubleshooting

Browser Not Launching

  • Verify bun or node is available: bun --version or node --version
  • Try --headless flag for environments without a display
  • Check if Playwright browsers are installed: bunx playwright install chromium

Connection Issues

  • Run /mcp in Claude Code to verify the server is listed and connected
  • Check the MCP server logs for errors
  • Ensure the command path is correct in your configuration

Localhost Access

  • Use --allowed-origins to explicitly allow localhost: --allowed-origins "http://localhost:*"
  • Verify the dev server is running before navigating

Timeouts

  • Increase --timeout-navigation for slow-loading pages (default: 60000ms)
  • Increase --timeout-action for slow element interactions (default: 5000ms)

Vision Mode vs Structured Mode

  • Default structured mode uses accessibility tree (faster, deterministic)
  • Vision mode (--caps vision) adds coordinate-based interaction for elements not in the accessibility tree
  • Prefer structured mode; use vision only when selectors are insufficient

Anti-Fabrication

  • Verify MCP connection status with /mcp before claiming Playwright tools are available
  • Do not assume browser capabilities without checking --caps configuration
  • Report actual page content from browser_snapshot output, not expected content
  • When reporting test results from testing capability tools, include actual pass/fail output
  • Reference core:anti-fabrication for full validation requirements

Usage Rules

  • Prefer --headless for CI, automated contexts, and agent workflows
  • Use --allowed-origins to restrict navigation scope when working with sensitive applications
  • Use vision capability only when structured selectors are insufficient
  • Verify MCP connection with /mcp before attempting browser operations
  • Use browser_snapshot (accessibility tree) over browser_take_screenshot (image) when extracting text content
  • Close browser sessions when done to free resources
  • For persistent auth, use --storage-state to save and restore session cookies

Sponsors

Details

Marketplace
vinnie357/claude-skills
Source
plugins/tools/playwright
Category
Tools
License
MIT
Keywords
playwright, mcp, browser, automation, screenshots

More from vinnie357/claude-skills

All 33