Add Playwright MCP to Claude Code

TL;DR

The shortest reliable setup is: confirm Node.js is available, add Playwright MCP with an explicit stdio command, verify the server reports connected, and run a read-only smoke test. Do not add persistent profiles, unrestricted file access, broad origins, or production credentials until that basic path succeeds.

Add Playwright MCP to Claude Code

Check the prerequisites

The official Playwright MCP repository currently lists Node.js 18 or newer as a requirement. Confirm that node --version, npx --version, and claude --version all work in the same terminal where you will add the server. This catches a common Windows and macOS problem: Node.js is installed, but the shell or Claude Code process has not inherited the updated PATH. Update Claude Code before troubleshooting an old command format or status display.

Register the stdio server

Run claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest from the project where you want to use the server. The name playwright is the label Claude Code displays; npx launches the Microsoft package. The double dash matters in the current Claude Code syntax because everything after it belongs to the server command rather than the Claude CLI. The shorter command shown in the Playwright repository may still work in compatible releases, but the explicit transport and separator make ownership of every argument clear.

Choose local, project, or user scope deliberately

Local scope is the default and stores a private configuration associated with the current project in your user configuration. It is a sensible starting point because it does not add a shared file to the repository. Project scope writes a team-shareable .mcp.json at the project root; Claude Code asks users to approve project-scoped servers, so review the command and package before committing it. User scope exposes the server across projects and is convenient for a personal development utility, but it also broadens where browser tools are available.

• --scope local: use for one developer and one project; this is the safest first setup.
• --scope project: use when the team has reviewed the server definition and wants it versioned in .mcp.json.
• --scope user: use only when the same browser server should be available in every project for that user.

Verify configuration and connection separately

An “Added” message proves only that Claude Code wrote the configuration. Run claude mcp list and look for Connected; use claude mcp get playwright to inspect the stored command and scope. Then open Claude Code in the intended project and run /mcp. A project-scoped server can show pending approval until the workspace is trusted and the server is approved. A failed connection means the process did not start or complete the MCP handshake, even though registration succeeded.

Use an inspect, act, and verify workflow

Prove the tool surface with a read-only test

Do not begin with login or form submission. Ask Claude Code to open a public URL, report the final URL and page title, identify one visible heading, and list one named link without clicking it. Then permit one navigation and ask for the new URL and heading. This small test verifies browser startup, navigation, accessibility snapshots, tool results, and state refresh while keeping the consequences near zero.

Write requests as task contracts

A useful browser request states the starting URL, desired outcome, allowed domains, permitted actions, prohibited actions, review checkpoints, and evidence of success. Tell the agent what result to achieve rather than dictating unverified click coordinates. For example: inspect the staging settings page, identify the webhook form, populate the listed values, report every field, and stop before saving. The goal remains stable even if the page layout changes.

• Inspect the current URL and accessible page structure before the first action.
• Locate controls by role, visible label, name, or stable test ID rather than coordinates.
• Perform one bounded action and wait for the expected state transition.
• Reinspect after navigation, refresh, modal changes, frame changes, or dynamic updates.
• Return the final URL and page evidence that directly proves the requested result.

Add configuration only when the task needs it

Playwright MCP supports options for browser choice, headless mode, isolated sessions, persistent user data, storage state, output files, timeouts, device emulation, and additional capabilities. Start with the default browser and profile behavior. Add --isolated for disposable sessions, --browser when a specific engine matters, or --output-dir when screenshots and traces need a controlled destination. Treat --user-data-dir and stored authentication state as sensitive configuration because they can retain cookies and account access.

Move stable checks into committed tests

MCP is well suited to exploration, debugging, and tasks whose exact path changes. Once the same assertion is needed on every build, convert it to a normal Playwright test with explicit fixtures, selectors, assertions, retries, and CI reporting. The MCP run can help discover the workflow, but the committed test becomes the reproducible artifact. If you are still choosing between browser MCP designs, the related browser MCP guide covers the decision criteria without duplicating this installation path.

Safety and debugging practices

Troubleshoot the failing layer, not the whole stack

• Command not found: confirm Node.js, npx, and Claude Code are available in the same shell and restart the terminal after PATH changes.
• Failed to connect: inspect claude mcp get playwright, run the stored npx command directly, and read the first process error.
• Pending approval: open the project interactively, trust the workspace, and review the project-scoped server definition.
• Browser will not start: check browser installation, executable permissions, sandbox restrictions, proxy settings, and profile conflicts.
• Element disappeared: reacquire the page snapshot after navigation or dynamic updates instead of reusing a stale reference.
• Repeated submission: inspect for a confirmation message, changed URL, or duplicate record before retrying.

Keep browser access narrower than the task

Use a test account or dedicated browser profile whenever possible. Keep passwords, API keys, recovery codes, and raw cookies out of prompts and retained logs. Playwright MCP documents origin filters, but it also warns that allowed origins are not a security boundary and do not control redirects. Do not treat a filter as a substitute for account isolation, least privilege, and human approval. Avoid unrestricted file access unless the workflow genuinely needs local files, and review every upload by exact path and destination.

Pause immediately before consequential actions

Read-only inspection can usually proceed inside the approved domain. Drafting text or filling an unsent form should stop at a review checkpoint. Sending messages, accepting legal terms, purchasing, publishing, changing permissions, uploading private data, or deleting records requires explicit approval immediately before the final action. The approval request should identify the target and payload so the person knows exactly what will change.

Where QVeris fits beside Playwright MCP

Use each layer for the work it handles best

• Use Playwright MCP when Claude Code must inspect rendered state, operate UI-only controls, or explore a changing web workflow.
• Use QVeris to discover and invoke a structured API or tool when typed inputs and predictable outputs can replace browser interaction.
• Combine them when an API prepares or validates structured data and Playwright MCP completes the interface-only step.
• Keep deterministic, repeated browser assertions in committed Playwright tests rather than rebuilding them as agent prompts.

QVeris does not install the local MCP server, manage its Node.js process, or approve Claude Code permissions. Its value begins when the broader agent workflow needs verified structured capabilities alongside browser automation. If the whole task is simply “install Playwright MCP locally,” stay with the Microsoft and Anthropic instructions above.

FAQ