playwright-mcp

Playwright MCP Browser Automation You are an expert at using the Playwright MCP server for live browser interaction. This skill teaches you to navigate pages, inspect elements, fill forms, and debug web UIs through direct browser control. Critical: These Are Direct Tool Calls MCP tools are direct tool calls — exactly like Read , Grep , or Bash . They are NOT CLI commands. CORRECT — call the tool directly: Tool: mcp__playwright__browser_navigate Parameters: { "url": "http://localhost:3010" } WRONG — do NOT shell out: Bash: claude mcp call playwright browser_navigate ... # This does not work All Playwright MCP tools use the mcp__playwright__ prefix. Critical: Always Snapshot Before Interacting browser_snapshot returns an accessibility tree with ref values for every interactive element. You must snapshot before clicking, typing, or hovering — the ref values are required for all interaction tools. Critical: Output Size Awareness Tool Output Size Notes browser_snapshot Medium-Large Full accessibility tree — scales with page complexity browser_take_screenshot Large Base64 image — use sparingly browser_console_messages Variable Can be very large on noisy apps browser_network_requests Variable Can be very large on API-heavy pages browser_navigate Small Returns page title only browser_click Small Returns snapshot after click browser_type Small Returns snapshot after typing Prefer browser_snapshot over browser_take_screenshot for understanding page structure. Screenshots are for visual verification only. Workflow 1: Navigate & Inspect Trigger: User says "open this page", "what's on the page?", "inspect the UI", "check the layout" Steps Navigate to the page: browser_navigate({ url: "http://localhost:3010/home/team-slug/settings" }) Get page structure (always do this before interacting): browser_snapshot → accessibility tree with ref values for all elements Analyze the snapshot: Identify interactive elements (buttons, links, inputs) by their ref values. Report page structure to user. Decision: Snapshot vs Screenshot Need Use Understand page structure, find elements browser_snapshot (structured, has ref values) Visual appearance, layout bugs, CSS issues browser_take_screenshot (visual image) Both structure and appearance Snapshot first, then screenshot if visual check needed Workflow 2: Form Interaction Trigger: User says "fill out the form", "submit the login", "type in the field", "select an option" Steps Snapshot to find form fields: browser_snapshot → identify input refs and their labels Fill fields (choose based on complexity): Single field: browser_type({ ref: "input-ref", text: "value" }) Multiple fields: browser_fill_form({ fields: [{ ref: "ref1", value: "val1" }, { ref: "ref2", value: "val2" }] }) Dropdown: browser_select_option({ ref: "select-ref", values: ["option-value"] }) Submit the form: browser_click({ ref: "submit-button-ref" }) Verify result: browser_snapshot → check for success message, error states, or navigation Key Patterns browser_fill_form is faster than multiple browser_type calls for multi-field forms Use browser_press_key({ key: "Enter" }) as alternative to clicking submit After submission, wait if needed: browser_wait_for({ text: "Success" }) then snapshot Workflow 3: Debug Investigation Trigger: User says "debug the page", "check for errors", "what API calls are happening?", "why isn't it working?" Steps Navigate to the problematic page: browser_navigate({ url: "..." }) Run these in parallel (they are independent): browser_console_messages → JavaScript errors, warnings, logs browser_network_requests → API calls, failed requests, status codes Snapshot the page: browser_snapshot → current UI state, error messages, loading states Investigate further: browser_evaluate({ expression: "document.querySelectorAll('.error').length" }) → run custom JS Workflow 4: Multi-Step Navigation Trigger: User says "go through the flow", "test the signup process", "walk through the wizard" Steps Navigate to starting page: browser_navigate({ url: "..." }) For each step: browser_snapshot → find the next action browser_click({ ref: "..." }) or browser_type({ ref: "...", text: "..." }) browser_wait_for({ text: "expected content" }) → if page loads async Handle dialogs if they appear: browser_handle_dialog({ accept: true }) → confirm/alert/prompt Go back if needed: browser_navigate_back Tool Reference Navigation Tool Purpose Parameters browser_navigate Go to URL url (required) browser_navigate_back Go back None browser_wait_for Wait for text or time text or timeout (ms) browser_tabs List/switch tabs None or index to switch Inspection Tool Purpose Parameters browser_snapshot Accessibility tree with refs None browser_take_screenshot Visual screenshot None browser_console_messages JS console output None browser_network_requests Network activity None Interaction Tool Purpose Parameters browser_click Click element ref (from snapshot) browser_type Type text ref , text browser_fill_form Fill multiple fields fields array of { ref, value } browser_select_option Select dropdown ref , values array browser_hover Hover element ref browser_drag Drag and drop startRef , endRef browser_press_key Keyboard input key (e.g., "Enter", "Tab") browser_file_upload Upload file ref , paths array browser_handle_dialog Confirm/dismiss dialog accept boolean Advanced Tool Purpose Parameters browser_evaluate Run JavaScript expression browser_resize Resize viewport width , height browser_close Close page None browser_install Install browser None browser_run_code Run Playwright code code string Troubleshooting "No browser running" or Connection Errors The Playwright MCP server manages its own browser instance. If tools fail: Try browser_install to ensure the browser binary is available Try browser_navigate to a simple URL — this may initialize the browser Elements Not Found After Navigation Pages with async content may not have rendered yet: Use browser_wait_for({ text: "expected content" }) before snapshot Use browser_wait_for({ timeout: 2000 }) for time-based waiting Proxied or Internal Domains The MCP browser cannot reach proxied or internal domains that require network tunnels. Use http://127.0.0.1:54321 directly for local Supabase. Snapshot Returns Very Large Output Complex pages produce large accessibility trees. If output is too large: Navigate to a specific sub-page rather than the full app Use browser_evaluate to query specific elements instead