claude-playwright

Claude Playwright integrates browser automation capabilities for Claude Code via MCP. It exposes a suite of tools to control a headless or visible browser, manage sessions, test workflows, and capture results. Users can navigate pages, click elements, fill forms, take screenshots, and extract data, all through Claude prompts. It also supports session persistence, multiple device profiles, AI-assisted selector caching, and test management, enabling robust end-to-end automation inside Claude.

To use it, first initialize the MCP configuration with the provided CLI commands, then let Claude issue commands like navigating to URLs, taking screenshots, saving and loading sessions, and saving tests. Available MCP tools include core browser actions (navigate, click, type, screenshot), form interactions (fill form, select option, hover, press key), session management (restore, save, list), and test management (save, run, find, library), plus debugging helpers. When interacting with Claude, you can say things like “Navigate to the login page and sign in” or “Take a screenshot of the dashboard,” and Claude will drive the browser accordingly using the Playwright backend.

The toolkit is designed for reliability with retry logic, intelligent error recovery, and clear error messaging. It also supports device profiles to test across viewports, and an intelligent cache for selectors to speed up repeated interactions.

Prerequisites:

• Node.js (LTS) installed on your machine
• npm or pnpm
• Access to run a local MCP server if you’re integrating with Claude Code

Step 1: Install the package globally (recommended) or as a dev dependency

npm install -g claude-playwright

Step 2: Install locally in your project (optional)

npm install --save-dev claude-playwright

Step 3: Initialize MCP configuration (base URL is where your app server runs)

npx claude-playwright mcp init --base-url http://localhost:3000

Step 4: Start your application server (example)

npm run dev

Step 5: Restart Claude Code or reload the MCP integration as described in the Quick Setup of the README.

Optional: Verify installation

npx claude-playwright mcp status

Tips and common issues:

• Ensure BASE_URL in the MCP config matches the actual URL your app serves.
• If MCP connection fails, check that the server process is running and that Claude Code can access the base URL.
• Sessions save cookies and authentication state; they are valid for 8 hours with auto-extension.
• Use profile management to test across devices and viewports (e.g., mobile vs desktop).
• For debugging browser actions, use the mcp_debug_console and mcp_debug_network tools.
• If you update claude-playwright, re-run mcp init to refresh configuration if needed.