I expected one command and a browser window. The command worked, but Claude Code labeled the new project-scoped server Pending approval. That small pause is why a useful setup guide must verify four layers instead of celebrating after the package downloads.
Playwright MCP for Claude Code is a tool-server connection that gives Claude Code structured browser automation through the Model Context Protocol. Claude Code is the client. The Playwright MCP process owns the browser tools, profile choice, and evidence returned from each action. It isn't a complete test strategy, and it doesn't automatically inherit everyday Chrome state.
What does Playwright MCP add to Claude Code?
Playwright MCP gives Claude Code named browser tools for page observation and action. The current 0.0.80 server in our run exposed navigation, snapshots, targeted find, click, form fill, JavaScript evaluation, network inspection, screenshots, tabs, console messages, and an unsafe Playwright-code escape hatch.
The official Playwright MCP guide lists Node.js 20 or newer and an MCP client such as Claude Code as prerequisites. It describes browser automation through structured accessibility snapshots rather than screenshot-only vision.
Should Claude Code use MCP, CLI, or an existing-browser route?
Choose the interface by the evidence the task must produce. MCP keeps interaction structured inside the agent loop. CLI keeps commands and files close to a coding workflow. An existing-browser route matters when approved login state is the hard requirement.
| Route | What it can do | What it cannot assume |
|---|---|---|
| Playwright MCP | Expose structured browser tools and live page evidence to Claude Code. | It doesn't become a durable Playwright Test suite or inherit personal Chrome sessions by default. |
| Playwright CLI | Run concise shell commands and save snapshots or output files for selective reading. | It can't run in a client without shell and filesystem access. |
| Existing-browser Space | Operate an independent browser workspace with eligible, approved state. | It doesn't provide Playwright Test fixtures, assertions, network mocking, or traces. |
For the full interface and context-cost comparison, read Playwright MCP vs CLI. This page stays focused on Claude Code registration and verification.
How do you add Playwright MCP to Claude Code?
Register the official npm package with Claude Code, then inspect the saved scope before launching a test. Project scope writes a shareable .mcp.json in that project. User scope makes the server available across projects and carries a wider trust surface.
claude mcp add --scope project playwright -- npx --yes @playwright/mcp@latest --isolated
claude mcp get playwright
claude mcp listOur command used Claude Code 2.1.221 and pinned @playwright/mcp 0.0.80 after resolving the current package. Claude wrote the expected project config and printed the full command. It also reported Pending approval. That was correct behavior: a project file shouldn't silently gain browser control merely because it exists.
Open Claude Code interactively in that trusted project, review the exact command and arguments, approve the server, then run the MCP status view again. Don't solve a trust prompt with a global permission bypass.
How do you verify the server, tools, browser, and result?
A valid verification produces evidence at four layers. Our direct MCP client test completed the same server and browser path without relying on an agent's sentence saying it worked.
| Layer | Our observed proof | Failure meaning |
|---|---|---|
| Server | MCP initialize and listTools completed. | Process, package, Node, or transport is broken. |
| Tools | 24 named browser tools were returned by version 0.0.80. | Claude may be connected to the wrong server or blocked by approval. |
| Browser action | browser_navigate opened the official Playwright MCP guide and wrote a YAML snapshot. | Browser launch, URL policy, network, or page load failed. |
| After-state | evaluate returned the title, seven H2s, 11 code blocks, and one Microsoft GitHub link. find returned three Claude Code matches; console errors were zero. | The action happened, but the requested result isn't proven. |
const result = await client.callTool({
name: "browser_evaluate",
arguments: {
function: "() => ({ title: document.title, h2: document.querySelectorAll('main h2').length })"
}
});
// Observed: { title: "Playwright MCP | Playwright", h2: 7 }How should Claude Code handle browser and login state?
Use the least persistent state that still completes the task. A fresh isolated browser is easiest to reproduce. Interactive login is useful for a one-off test when a human can approve MFA. Storage state or a persistent user-data directory can support repeat runs, but those files become credentials and need the same controls as API keys.
| State choice | Best fit | Boundary |
|---|---|---|
| --isolated | Public pages, fixtures, and reproducible smoke checks | Login state disappears with the session. |
| Interactive login | Occasional test behind MFA with a human present | It isn't unattended automation. |
| Storage state or user data | Approved repeat testing with controlled test accounts | The artifact can expose cookies and account access. |
How do you troubleshoot missing tools and failed runs?
Troubleshoot from Claude Code outward. The first error is usually more valuable than the fifth reinstall.
- Confirm the exact project and scope. Run claude mcp get playwright from the directory that owns .mcp.json.
- Resolve approval. Pending approval is a host trust state, not a Playwright crash.
- Run the package command directly with --version or --help under Node 20 or newer.
- Reduce the task to one public URL, one observation, one screenshot, and one after-state assertion.
- Only then add profile state, permissions, proxies, or extension attachment.
If the server starts but Claude can't see tools, compare the configured command with the process Claude actually launched. Duplicate manual and plugin installations can expose two servers with different arguments. Remove the duplicate, restart Claude Code, and inspect again.
How do you use Playwright MCP safely in testing workflows?
Treat MCP output as evidence, not a verdict. Give Claude Code a deterministic fixture or test account, define the expected URL and visible result, and save a screenshot or snapshot when the check fails. A reviewer needs to rerun the command without reconstructing the conversation.
Where does ego (lite) fit, and where does it not?
For a different Claude Code job, ego (lite) can operate a real browser in an independent Space, reuse eligible user-authorized state, and batch several browser checks inside one ego-browser JavaScript round. On September 10, we used one Space to test eight article pages at 1440-pixel desktop and 390-pixel mobile widths. The run checked canonicals, language tags, one H1, heading order, image loads and alt text, anchor targets, code overflow, horizontal overflow, plus a real article-outline click.
This route doesn't replace Playwright's test runner. Use ego (lite) for browser QA when an agent needs an inspectable browser workspace or approved live state. Keep Playwright for assertion-heavy E2E suites, network mocking, trace artifacts, and Linux headless CI.
FAQ
What command adds Playwright MCP to Claude Code?
Use claude mcp add playwright -- npx @playwright/mcp@latest, adding --scope project or --scope user deliberately. Review the current Microsoft README before copying extra flags.
Why does Claude Code say Pending approval?
Project-scoped MCP configuration requires trust approval. Open Claude Code interactively in the trusted project, review the command, approve it, and check status again.
How do I know Playwright MCP really works?
Verify server initialization, tool discovery, one browser action, and an independently read after-state. A package install or agent message alone is insufficient.
Does Playwright MCP use my existing Chrome login?
Not by default. Browser state depends on isolated mode, a user-data directory, storage state, CDP attachment, or the Playwright extension route selected in configuration.
Is the Claude Playwright plugin identical to manual MCP registration?
Don't assume so across every release. Anthropic's plugin page proves a plugin entry exists, while Microsoft documents the manual MCP command. Inspect the command Claude actually launches.
Does Playwright MCP write a test suite?
No. It can operate pages and help draft tests, but durable assertions, fixtures, retries, traces, and reports belong in Playwright Test code and CI.
Should I use MCP or Playwright CLI with Claude Code?
Use MCP for structured exploratory browser tools inside the agent loop. Use CLI for shell-oriented coding tasks where concise commands and file artifacts fit the workflow.
Can I turn snapshots off to save context?
Version 0.0.80 exposes snapshot-mode full or none. Disabling snapshots can reduce returned page structure, but it also removes evidence the agent uses to choose elements.
Is allowed-origins a security boundary?
No. The current CLI help says it doesn't affect redirects and must not be treated as a security boundary. Pair it with restricted credentials, filesystem roots, and test accounts.
Can ego (lite) replace Playwright MCP?
ego (lite) is an alternative execution environment for an independent browser Space and approved state. It doesn't replace Playwright Test or MCP-specific integrations.
