Playwright Mcp

Playwright MCP — AI Agent Browser Automation

Playwright MCP is a Model Context Protocol server that lets AI agents control real browsers through structured accessibility snapshots. Refs like e5, e12 give deterministic handles to every interactive element — no pixel-guessing, no brittle CSS selectors.

> Read references/tools.md for the full tool catalogue before choosing an approach. > Read references/config.md for CLI flags, capabilities, and JSON config options. > Read references/patterns.md for copy-paste workflow recipes.

---

Core Mental Model

browser_navigate → browser_snapshot → interact via refs → browser_snapshot (verify)

Every action follows this cycle. The snapshot is the ground truth. Never assume page state — always re-snapshot after an action.

---

Decision Tree: What to Use

1. Snapshot vs Vision Mode

| Situation | Use | |-----------|-----| | Standard web app — forms, buttons, links, tables | Snapshot (default) | | Canvas, SVG, chart, game UI, custom drawn widget | Vision mode (--caps=vision) | | Verifying visual layout, pixel correctness | Screenshot + snapshot together |

Rule: Snapshots for 90%+ of tasks. Vision only for elements absent from the accessibility tree.

2. Which Capability to Enable

Enable only what you need — each capability adds tokens to every interaction:

| Need | Add to --caps= | |------|-----------------| | Mock API responses / intercept network | network | | Cookies, localStorage, auth state save/restore | storage | | Verify elements, generate .spec.ts test code | testing | | Canvas/chart coordinate-based clicking | vision | | Export page as PDF | pdf | | Video recording, tracing | devtools |

Minimal config (no capabilities) is fastest and cheapest on tokens.

3. Token Budget Awareness

A single browser_navigate on a content-rich page can return thousands of tokens. Across a multi-step session this compounds.

| Practice | Saves Tokens | |----------|-------------| | Enable only needed capabilities | High | | Use browser_snapshot only when you need to verify or find a ref | High | | Avoid browser_take_screenshot unless visual proof is required | Medium | | Use browser_fill_form (one call) instead of multiple browser_type | Low | | Stop tracing/video when not debugging | Medium |

---

Standard Workflow Templates

Login Flow

browser_navigate { url }
browser_snapshot                          → find email/password refs
browser_type { ref: "e3", text: email }
browser_type { ref: "e5", text: password }
browser_click { ref: "e7" }              → submit button
browser_snapshot                          → verify dashboard appeared

Save state after login so you never repeat it:

browser_storage_state                     → writes auth-state.json

Restore on next run: --storage-state=./auth-state.json

Form Fill (Multi-Field)

browser_navigate { url }
browser_snapshot
browser_fill_form {
  fields: [
    { ref: "e3", value: "..." },
    { ref: "e5", value: "..." }
  ]
}
browser_click { ref: "e9" }              → submit
browser_snapshot                          → verify success message

API Mocking

Requires --caps=network:

browser_route {
  pattern: "**/api/users",
  body: '[{"id":1,"name":"Alice"}]',
  contentType: "application/json"
}
browser_navigate { url }
browser_snapshot                          → page now uses mocked data

Debugging a Broken Page

browser_navigate { url }
browser_console_messages { level: "error" }   → read JS errors first
browser_snapshot                              → inspect element tree
browser_take_screenshot                       → visual evidence

If the problem is complex, start a trace:

browser_start_tracing
[... reproduce the issue ...]
browser_stop_tracing                          → share trace.zip with team

Generate Playwright Test Code

Requires --caps=testing. After completing an exploratory flow:

browser_generate_locator { ref: "e5" }
→ page.getByPlaceholder('What needs to be done?')

Use browser_verify_text_visible, browser_verify_element_visible to add assertions that translate to expect() calls.

---

Common Pitfalls

| Mistake | Correct Approach | |---------|-----------------| | Acting on a stale ref after page re-render | Re-run browser_snapshot before each new interaction | | Using vision mode on a standard form | Default to snapshot — forms are always in the accessibility tree | | Taking screenshots repeatedly to "check" state | Use browser_snapshot — it's structured and token-cheaper | | Opening storage/network capabilities you don't need | Only add capabilities matching the task | | Forgetting browser_wait_for on dynamic pages | Wait for content to appear before snapshotting | | Logging in on every agent run | Save browser_storage_state once, load with --storage-state | | Multiple browser_type calls for one form | Use browser_fill_form — one call, fewer tokens |

---

Refs: How They Work

After browser_snapshot, every interactive element has a ref like e5. These refs are:

• Ephemeral — valid only until the next page render
• Deterministic — clicking e5 always hits the same element
• Auto-waitable — Playwright waits for the element to be ready before acting

Always re-snapshot when you suspect the page has changed.

---

Quick Config Reference

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--caps=network,storage,testing"]
    }
  }
}

Key flags: --headless, --browser=firefox, --device=iPhone 15, --isolated, --storage-state=./auth.json, --port 8931 (HTTP server mode).

Full options → references/config.md Full tool list → references/tools.md Copy-paste recipes → references/patterns.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Razaib-khan
• Source: Razaib-khan/ForgeWeave
• License: MIT

Install and usage instructions live in the source repository linked above.