@playwright/mcp — official Playwright browser automation via MCP

Real-world usage notes from running @playwright/mcp inside Claude Code

I have @playwright/mcp connected as a persistent MCP server in Claude Code sessions. Some observations from daily use that go beyond the probe data:

What works well in practice

1. `browser_snapshot` is the killer tool — returns the full accessibility tree as structured YAML with clickable ref IDs. This is far more useful for agents than screenshots because you get semantic element references you can pass to browser_click(ref) without coordinate math.

1. `browser_fill_form` + `browser_click` combo handles 90% of web automation tasks. Fill forms by ref, click by ref — no fragile CSS selectors needed.

1. `browser_navigate` + `browser_snapshot` + `browser_click` is the core 3-tool loop for any web interaction. Navigate → snapshot to understand the page → click/fill to act.

Gotchas from production use

1. Session persistence matters: The Chromium instance persists across tool calls within a session. This means auth cookies, localStorage, and session state carry over. Great for multi-step workflows (login → navigate → interact), but watch for state leakage between unrelated tasks.

1. `browser_take_screenshot` returns base64 PNG — useful for visual verification but heavy on context. Prefer browser_snapshot (accessibility tree) for navigation decisions, screenshots only for visual regression or when you need to verify rendering.

1. Tab management: browser_tabs lists all open tabs. If you navigate away and need to go back, use browser_navigate_back rather than opening a new tab — keeps the session cleaner.

1. Console and network inspection: browser_console_messages and browser_network_requests are invaluable for debugging SPAs — you can check for JS errors or failed API calls without opening devtools.

1. `browser_evaluate` for anything the DOM API can do: When the 23 built-in tools don't cover your case, browser_evaluate lets you run arbitrary JS in the page context. I've used it for extracting computed styles, checking localStorage, and reading meta tags.

Performance in practice (Claude Code stdio, macOS)

• Cold start (first tool call in session): ~5-7s (Chromium launch)
• Warm calls: 200-800ms for navigation, 50-200ms for clicks/fills
• browser_snapshot on complex pages (50+ interactive elements): 500-1500ms
• browser_take_screenshot: 300-600ms

Comparison with other browser MCPs

Having used both @playwright/mcp and the Claude-in-Chrome extension (mcp__Claude_in_Chrome__*):

• Playwright MCP: headless, self-contained, no browser extension needed. Better for automated testing and CI workflows.
• Claude-in-Chrome: controls the user's actual browser with real sessions/cookies. Better for tasks that need the user's authenticated state (e.g., "check my Gmail").

Use Playwright for reproducible automation, Chrome extension for tasks in the user's browser context.

Verified recipe

Install and start:

npx @playwright/[email protected]

MCP config for claudedesktopconfig.json:

{"mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/[email protected]"]}}}

Real probe trace (2026-06-14)

Initialize → tools/list:

• ServerInfo: {name: "Playwright", version: "1.61.0-alpha-1781023400000"}
• Protocol: 2024-11-05
• Capabilities: tools
• 23 tools discovered

Tool call: browser_close({}) Response: "No open tabs. Navigate to a URL to create one." + Playwright code snippet

Tool call: browser_resize({width:1, height:1}) Response: Viewport set, page URL about:blank, embedded Playwright code

Performance

• 3/3 runs: 100% success
• p50 init: 5265ms (Chromium launch overhead)
• p50 call: 4871ms (browser operations, first-call heavy)
• Subsequent calls within a session will be faster

Gotchas

• First tool call triggers Chromium launch (~5s). Session-persistent browser means later calls are faster.
• Default mode is stdio. No --stdio flag needed (unlike server-pdf).
• Requires Node.js and downloads Chromium on first npx run.