Live browser interaction via Playwright MCP — navigate pages, click buttons, fill forms, take screenshots.
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.
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 prefix.
mcp__playwright__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.
| 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.
Trigger: User says "open this page", "what's on the page?", "inspect the UI", "check the layout"
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.
| 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 |
Trigger: User says "fill out the form", "submit the login", "type in the field", "select an option"
Snapshot to find form fields:
browser_snapshot → identify input refs and their labels
Fill fields (choose based on complexity):
browser_type({ ref: "input-ref", text: "value" })browser_fill_form({ fields: [{ ref: "ref1", value: "val1" }, { ref: "ref2", value: "val2" }] })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
browser_fill_form is faster than multiple browser_type calls for multi-field formsbrowser_press_key({ key: "Enter" }) as alternative to clicking submitbrowser_wait_for({ text: "Success" }) then snapshotTrigger: User says "debug the page", "check for errors", "what API calls are happening?", "why isn't it working?"
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
Trigger: User says "go through the flow", "test the signup process", "walk through the wizard"
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 | 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 |
| 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 |
| 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 |
| 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 |
The Playwright MCP server manages its own browser instance. If tools fail:
browser_install to ensure the browser binary is availablebrowser_navigate to a simple URL — this may initialize the browserPages with async content may not have rendered yet:
browser_wait_for({ text: "expected content" }) before snapshotbrowser_wait_for({ timeout: 2000 }) for time-based waitingThe MCP browser cannot reach proxied or internal domains that require network tunnels. Use http://127.0.0.1:54321 directly for local Supabase.
Complex pages produce large accessibility trees. If output is too large:
browser_evaluate to query specific elements instead