Skip to main content

Getting Started

Prerequisites​

  • Node.js 20 or newer
  • An MCP client: VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, or similar

Installation​

Add the Playwright MCP server to your client:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

See Client Setup for client-specific instructions. The browser downloads automatically on first use.

First interaction​

Ask your AI assistant:

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

The assistant calls MCP tools to open the browser, navigate, and interact — returning accessibility snapshots at each step:

→ browser_navigate { url: "https://demo.playwright.dev/todomvc" }

  - heading "todos" [level=1] [ref=e3]
  - textbox "What needs to be done?" [ref=e5]

→ browser_type { target: "e5", text: "Buy groceries", submit: true }

  - heading "todos" [level=1] [ref=e3]
  - textbox "What needs to be done?" [ref=e5]
  - list [ref=e8]:
    - listitem [ref=e9]:
      - checkbox "Toggle Todo" [ref=e10]
      - text: Buy groceries
  - contentinfo [ref=e12]:
    - text: 1 item left

The workflow​

Every MCP interaction follows this cycle:

  1. Navigate — browser_navigate opens a URL
  2. Snapshot — tools return the accessibility tree with element refs
  3. Interact — the LLM passes a ref as the target of a click, type, or fill
  4. Re-snapshot — each action returns updated state

The browser opens in headed mode by default so you can watch. Pass --headless to run without a visible window.

Example prompts​

Go to https://example.com and take a screenshot.
Open https://demo.playwright.dev/todomvc, add three todos,
check off the first one, and take a screenshot.
Navigate to https://news.ycombinator.com and list the top 5 stories.
Save the current browser state to auth.json so we can skip login next time.

Next steps​