Blog Blog

How to install Playwright MCP on Claude Code

Playwright MCP connects Claude directly to your local Playwright setup, enabling fast AI-generated tests and hands-free browser automation inside your editor.

Playwright
User

TestDino

Dec 11, 2025

How to install Playwright MCP on Claude Code

Shipping faster only works when testing keeps pace, because speed without reliability turns releases into risks.

Manual testing breaks down as releases accelerate. Repeating flows by hand is slow, error-prone, and unsustainable. That's why teams turn to Playwright automation.

But even automation has limits: someone still needs to write, debug, and maintain every test. This is where Playwright MCP changes the game by letting AI understand your UI and generate tests in real-time.

Before bringing AI into the workflow, it’s important to understand the automation layer underneath.

TLDR

1. Install Node.js (LTS).

2. Sign in to Claude Desktop.

3. Open Settings → Developer → Edit MCP configuration file.

4. Add Playwright MCP as a local server using `npx`.

5. Restart Claude Desktop to apply changes.

6. Verify the setup by running a simple browser action (for example, automate a login flow on app.testdino.com).

If you want to see the full setup in action, watch this video.

What is a Playwright?

Playwright is a modern browser automation framework for testing real user interactions across Chromium, Firefox, and WebKit from a single codebase.

It improves reliability with auto-waiting and stable selectors, but engineers still need to write, debug, and maintain the test logic.

And this is exactly where Playwright MCP changes the game.

What is a Playwright MCP?

Playwright MCP connects AI models directly to a Playwright-controlled browser, allowing them to understand the UI through the accessibility tree instead of relying on screenshots.

This enables faster and more accurate test generation while keeping all execution local and your application data secure.

Now that you know what Playwright MCP does, let’s walk through how to install and run it with Claude Desktop and Claude Code.

What is Claude Desktop?

Claude Desktop is a desktop application that runs the Claude AI assistant locally on your machine.

It allows direct interaction with files and tools and can connect to systems like Playwright MCP for real browser automation.

First, let’s see the installation process for Claude Desktop

How to install Playwright MCP on Claude Desktop

To install Playwright MCP on Claude desktop, first install NodeJS and then sign in to Claude desktop. After signing up, navigate the app settings and edit the MCP configuration file.

Add Playwright MCP as a local server using npx and restart Claude Desktop.

Verify the setup by running a simple browser action to confirm the connection.

Once the flow is clear, let’s walk through each step in detail so you can complete the setup without missing anything.

To begin Claude Desktop Playwright MCP integration, we first need to prepare your Claude Desktop Client environment.

1. Setup Claude Desktop

Before starting the setup, make sure the following requirements are in place.

Prerequisites

  • Node.JS LTS and npm are available on your system.
  • Basic familiarity with CLI (Command Line Interface).

To see the full setup in action, you can also refer to this video tutorial for installing Playwright MCP and verifying integration.

Open Claude Desktop Settings using Ctrl +, on Windows or Cmd +, on macOS, then navigate to the Developer tab.

Claude Desktop settings screen showing Local MCP servers configuration with Edit Config option in Developer settings.

Click Edit Config to open the claude-desktop-config.json file

You can also access this file directly at

In Windows:

bash
C:\Users\{username}\AppData\Roaming\Claude\claude-desktop-config.json

Or in MacOS:

bash
~/Library/Application Support/Claude/claude-desktop-config.json

2. Configure Claude Desktop JSON

This configuration tells Claude Desktop where to find and launch the Playwright MCP server:

claude_desktop_config.json
{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }
macOS Finder showing claude_desktop_config.json with Playwright MCP server configuration using npx and @playwright/mcp.

With the configuration saved, Claude Desktop is ready to launch Playwright MCP, but for this, you have to reopen Claude Desktop to apply the changes.

Now, the final step is to confirm everything is working as expected.

3. Check Playwright MCP Connection

In the Developer or MCP settings panel, you should see Playwright listed as a running local MCP server.

Claude Desktop settings showing a local MCP server configuration with Playwright running via npx and @playwright/mcp.

Once you verify Playwright MCP is running in the settings panel, you can proceed to test it with a simple example. This ensures your setup is functioning correctly before integrating it into workflows.

4. Example

To make sure everything is configured correctly, let’s run a small example that tests the connection and functionality.

Type this prompt in Claude Desktop:

prompt
Navigate to the TestDino URL, wait until the page is fully loaded and any loaders or animations are complete, and capture a screenshot of the hero section

Expected Output: Browser opens, page stabilizes, full-page screenshot saved.

Claude interface showing Playwright MCP browser actions capturing a screenshot of the TestDino website hero section.

With this example, we’ve verified that Playwright MCP is working correctly. If you run into any issues, refer to the troubleshooting section for solutions.

Now that Playwright MCP is running smoothly in Claude Desktop, let’s move on to the installation process in Claude Code.

What is Claude Code?

While Claude Desktop is UI-driven, some users prefer the terminal. Claude Code is a CLI-first interface designed for working directly from the command line.

It integrates tightly with projects and scripts, making it ideal for automation-heavy or CI-oriented workflows.

With that context, let’s move into the installation steps.

How to install Playwright MCP on Claude Code

Now let’s walk through the Playwright MCP setup for Claude Code, starting with the required tools and prerequisites you’ll need before installation.

1. Setup Claude Code

Before installing Claude Code, make sure you have the following in place.

Prerequisites

You need one of the following to use Claude Code

  • A Claude account with an active subscription
  • An Anthropic Console account with sufficient credits

Without either option, Claude Code cannot authenticate or run.

Once Claude Code is installed, you can proceed to configure Playwright MCP to enable browser automation directly from the terminal.

2. Integrate Playwright MCP

First, start Claude Code in the terminal using the Claude command.

Now, Run the following command in the terminal to install and attach Playwright MCP

bash
claude mcp add playwright npx @playwright/mcp@latest
Claude CLI showing the command to add Playwright MCP using npx and confirming browser automation tools are available.

After setting up Playwright MCP in Claude Code, the next step is to confirm that the installation is working correctly by verifying the integration.

3. Verify Playwright MCP Integration

After installing Playwright MCP in Claude Code, verify the setup by running the /mcp command. Playwright should appear as an active local MCP server.

Command-line interface showing Playwright MCP server connected successfully and listed under managed MCP servers.

To make sure the setup is fully functional, let’s try a simple example using Playwright MCP

4. Example

For example, you can instruct Claude Code to open a URL and take a screenshot.

prompt
Open https://app.testdino.com in a real browser session. Log in using the credentials [email protected] and the provided test password. Verify that the dashboard loads successfully, then log out of the application. Capture a screenshot after login and after logout. Based on these actions, generate a complete Playwright test script that reproduces the same login and logout flow.

Expected Result: Claude Code executes the test, opens the site, waits for the loader to clear, and saves a full-page screenshot as fullpage.png with no errors.

Playwright MCP test execution output showing a successful login and logout flow completed in a real browser session.

This example confirms the setup is working and ready for real automation workflows.

Once you’ve confirmed that the example runs successfully, let’s look at common errors and troubleshooting tips.

Common errors and Troubleshooting

If setup fails, use the table below to diagnose and fix the issue quickly.

Issue Symptom Quick Fix
MCP Not Detected ”No MCP servers” error Check the mcpServers key in config files, validate JSON syntax, use forward slashes in paths, run claude doctor
”npx” Command Not Found MCP start fails Install Node.js 18+, restart Claude Code and terminal, verify with npx --version, check PATH configuration
Browser Launch Fails ”Failed to launch Chromium” Run npx playwright install --with-deps to install browsers and system dependencies, ensure proper permissions on macOS/Linux
Config Changes Not Loading Old config persists Fully quit Claude Code, restart the application, verify the config file location and syntax
MCP Unavailable in Prompts Claude denies Playwright use Run /mcp command to check server status, update MCP server packages, restart Claude Code

For common issues, we also have guides that might help you, such as fixing ‘Connection Refused‘ errors related to network and port conflicts. If you run into ‘Command Not Found‘ errors or need Node.js and PATH fixes, we‘ve got that solved too.

Conclusion

Setting up Playwright MCP with Claude Desktop and Claude Code enables reliable, AI-driven browser automation for real-world testing.

With AI now operating directly in your execution loop, you can move beyond test creation and focus on scaling coverage, diagnosing failures faster, and improving overall test quality.

As your automation grows, tools like TestDino help analyze results and surface insights through structured reporting and dashboards.

FAQs

Playwright MCP lets AI tools like Claude directly control Playwright as an execution layer, not just generate test code. It enables real browser actions from AI prompts instead of copy-paste workflows.

Stop wasting time on
flaky tests broken builds re-run roulette false failures

Get Started

Get started fast

Step-by-step guides, real-world examples, and proven strategies to maximize your test reporting success

Playwright Test Execution History
Playwright

Playwright Test Execution History Across Runs and CI

Attachment Details How-to-install-Playwright-MCP-on-Other-IDEs
Playwright

How to install Playwright MCP on Other IDEs

Automating Visual Regression Checks with Playwright MCP
Playwright

Automating Visual Regression Checks with Playwright MCP

Browse all