Check your Node and npx setup before debugging an MCP server launch
You will confirm the Playwright MCP launch command starts on its own and pin a known version if @latest will not start. This keeps you from chasing browser errors before the server has launched.
- Check npxConfirm the client and terminal resolve the same npx
- Run the package by handConfirm it starts with the same version string
- Verify the config shapeUse the single command string that worked in Cursor
- Pin a version if neededUse v0.0.29 when @latest fails to start
- Restart and confirm toolsCheck that the Playwright tools are listed
Why it matters
In Cursor, the official Playwright MCP config using @latest failed to start for several users, and pinning @playwright/mcp@v0.0.29 is the change that worked for them (source (opens external site)). The issue is marked closed, yet reports from July 2025 still describe the failure, so treat the pin as a working workaround rather than an upstream fix. Confirm the launch works before you read any browser-level error.
Steps
-
Run
npx --versionin your terminal, then run the same check from the environment your MCP client uses. Both should resolve the same Node and npx installation. -
Run the Playwright MCP package by hand from a terminal using the exact version string your config uses. If it fails here, the problem is in the launch, not in the client.
-
Open your MCP config and check the Playwright entry. In Cursor, the config that worked for users was a single command string with an empty env object:
{
"mcpServers": {
"playwright": {
"command": "npx @playwright/mcp@v0.0.29",
"env": {}
}
}
}
-
If
@latestfails to start and the pinned version starts, keep the pin while you investigate. Users reported that the downgrade was what fixed it, even after following the official README (source (opens external site)). -
For a project-level
.mcp.jsonused with Claude Code, the Playwright entry takes"type": "stdio","command": "npx", and an args array holding the package name plus"--isolated", along with"env": {}. Add--isolatedonly when you are fixing a browser profile lock, since it targets that error and not startup (source (opens external site)). -
Restart the MCP client after each config change, then check that the Playwright tools appear in its tool list before you go further.
-
Once the server starts cleanly, move on to runtime problems such as profile locks or session behavior.
Common mistakes
- Reading browser errors before the server has launched.
- Treating
@latestas always correct when a pinned version is the one that starts. - Adding
--isolatedto fix a startup failure. That flag addresses a profile-lock error (source (opens external site)). - Forgetting that a version pin is temporary. Note it so you can revisit it later.
Checklist
0 of 8 done