Learn how to quickly install Playwright MCP on Windsurf using the MCP Marketplace or CLI, enabling AI-driven test execution and real browser integration.
Pratik Patel
Jan 2, 2026
Modern Playwright teams can write tests easily, but execution often reveals failures without context, slow feedback, and tricky debugging.
AI can help in these moments, but only when it understands how your tests actually run.
With Playwright MCP in Windsurf, AI observes real browser behavior, test results, and runtime conditions, making its suggestions practical and actionable.
Open Windsurf Settings using Ctrl +, or Cmd +,
Switch to the Cascade tab
Open the MCP Marketplace and search for Playwright MCP
Click Install to add the MCP integration
Playwright MCP is enabled automatically with no manual setup
Confirm Playwright MCP appears as active in the Marketplace
Verify by asking Windsurf AI to run a real browser action, like opening a page or taking a screenshot (e.g., Open Windsurf, navigate to testdino.com, and capture a screenshot of the hero section.
Before understanding how MCP enhances execution, it’s important to clarify the core tool it builds on.
Playwright is an open-source end-to-end testing framework for modern web applications. It runs tests across Chromium, Firefox, and WebKit and reliably handles real user behavior such as navigation, waits, and complex UI interactions.
Before looking at specific benefits, it’s worth seeing how MCP changes the way Windsurf interacts with your tests.
Playwright MCP is a Model Context Protocol implementation that exposes a live Playwright execution environment to AI tools. It gives AI access to real browser sessions, test execution flow, and failure signals instead of static source code.
Before looking at specific benefits, it’s worth seeing how MCP changes the way Windsurf interacts with your tests.
Windsurf is an AI-first IDE created by Windsurf Labs for agent-driven development, allowing AI to not only suggest code but also understand projects, run tools, and handle multi-step workflows. It aims to make complex development tasks faster and smarter.
Playwright MCP allows Windsurf’s AI to move beyond static code suggestions by interacting directly with a live browser session, including the DOM, network activity, and runtime state.
This means the AI can see what actually happened during a test run, diagnose failures based on real behavior, and adapt tests immediately, cutting down trial-and-error debugging and making complex, multi-step workflows more reliable.
Before you dive into installation, it’s important to ensure your environment is properly set up so Playwright MCP can run reliably.
To successfully install Playright MCP using Windsurf, you need these solid foundations.
Once your environment is stable, you can proceed with installation. Playwright MCP can be added via Quick Installation from the Marketplace or a Custom Installation for full control.
Let's start the process.
Hit Ctrl +, or Cmd +, to open Windsurf Settings. By Default, it opens the General tab.
Navigate to the Cascade tab, which lists IDE integrations and extensions. Click the MCP Marketplace button to access available MCP integrations.
From here, you can set up Playwright MCP using two methods.
After opening the MCP Marketplace, search for Playwright MCP in the Search box, and you will MCP listed as shown in the image below.
First, install it as a dev dependency:
or with pnpm:
We have installed Playwright MCP using CLI now enable it. You can open the global MCP configuration file by clicking the settings icon in the MCP marketplace
Save the file. Windsurf will read it automatically.
Navigate back to the MCP Marketplace, Playwright MCP should appear in the list.
Once Playwright MCP is integrated, the fastest way to validate the setup is to let Windsurf drive a real browser task end-to-end.
Ask Windsurf’s AI to perform the following:
'Open https://app.testdino.com in a real browser session and log in using [email protected] with the provided test password. Verify the dashboard loads, capture a screenshot, then log out and capture another screenshot. Generate a complete Playwright test that reproduces this login–logout flow exactly as executed.'
Expected output:
If this example does not behave as expected, the issue is almost always environmental or configuration-related, which is exactly what the next section helps you diagnose.
If the setup does not behave as expected, the issues below cover the most common problems teams encounter and how to resolve them quickly.
| Issue / Symptom | Likely Cause | What to Do |
|---|---|---|
| MCP shows red status, or tools are disabled | MCP server failed to start due to config or spawn issues | Restart Windsurf, recheck the MCP config JSON, and verify the command runs correctly in the terminal |
| Playwright MCP appears installed, but does nothing | Node version mismatch between the terminal and the IDE | Ensure Windsurf uses the same Node binary as your terminal (Node 18 or higher) |
| The browser does not launch or times out | Playwright browsers are not installed | Run npx playwright install before retrying |
| MCP config not picked up | The MCP config file is in the wrong location or invalid JSON | Open the MCP config via Marketplace settings and validate the JSON syntax |
| MCP fails silently on Windows | npx not resolved correctly in the shell | Verify npx works in the terminal and avoid global installs |
Once these common issues are addressed, you should have a stable Playwright MCP setup and can confidently move forward with regular automation workflows.
At this point, Playwright MCP should feel like an execution layer, not just another integration.
Windsurf is no longer inferring behavior from code. It is observing real browser runs and reacting with accurate, context-aware actions.
This cuts down debugging time, removes guesswork, and makes AI assistance genuinely useful in daily automation work. Test creation, failure analysis, and workflow automation become more intentional and far less manual.
Once execution is reliable, the next bottleneck is visibility.
If you want clearer insights into runs, failures, and trends over time, a reporting tool like TestDino can help turn raw Playwright output into something teams can actually reason about and act on.
Execution Creates Evidence
Screenshots, logs, and retries only help when they’re easy to review and reason about.
You can update via the MCP Marketplace in Windsurf or update the dev dependency using npm or pnpm.
Table of content
Step-by-step guides, real-world examples, and proven strategies to maximize your test reporting success
