microsoft/playwright installation guide

Install Playwright for Claude Code on macOS Tahoe (Apple silicon)

What you are installing

Playwright is Microsoft’s Apache-2.0 framework for automating and testing websites in Chromium, Firefox, and WebKit. The repository documents several separate ways to use it: a test runner, a programming library, a command-line interface for coding agents, an MCP server, and a VS Code extension.

For Claude Code, the most direct documented setup is **Playwright MCP**. MCP stands for Model Context Protocol. It gives Claude Code a set of browser-control tools for navigation, form filling, screenshots, network mocking, storage management, and related tasks. Playwright describes this approach as using structured accessibility snapshots rather than requiring a vision model.

**Claude Code classification:** this repository relates to Claude Code through a **model-visible tool surface** provided by an MCP server. It also offers a separate external CLI designed for coding agents and optional skills that can enrich agent integration. It is not documented here as a conventional Claude Code plugin with its own marketplace manifest or lifecycle hooks.

Compatibility and prerequisites

The repository’s compatibility table explicitly supports macOS for Chromium, Firefox, and WebKit, in both headless and headed operation. It does not name macOS Tahoe specifically, but no Tahoe-specific workaround is documented. A repository test example also contains an Apple-silicon-style `mac_arm` Firefox path, providing evidence that ARM Mac browser artifacts are used within the project.

Before proceeding, you need:

• An Apple-silicon Mac running macOS Tahoe.
• Terminal access. Open **Terminal** from Applications → Utilities, or find it with Spotlight.
• Claude Code installed so that its documented `claude` command is available.
• Node.js tooling that provides `npx`. The supplied repository files do not state a minimum Node.js version or provide a first-party Node.js installation command, so this guide does not invent one.
• Internet access for `npx` to obtain the published Playwright MCP package.

If either Claude Code or Node.js tooling is absent, install it from its first-party source before continuing. No Homebrew setup command is supplied by this repository, so none is recommended here.

Recommended installation: Playwright MCP for Claude Code

Open Terminal and copy and paste the repository’s documented Claude Code command:

claude mcp add playwright npx @playwright/mcp@latest

Here is what each part means:

• `claude mcp add` asks Claude Code to register an MCP server.
• `playwright` is the server name that will identify the integration.
• `npx` launches the published package.
• `@playwright/mcp@latest` selects the latest published Playwright MCP package.

Allow the command to finish. The supplied files do not document a second installation command, an Apple-silicon flag, or a separate browser download command for this MCP route. Do not substitute repository-development commands from internal test documentation: those are for contributors running Playwright’s own Bidi tests, not for ordinary Claude Code users.

Try the installation

Start or return to Claude Code after registration. Ask it to perform a small, harmless browser task. The repository provides this example request:

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

This sentence is a prompt for Claude Code, not a Terminal command. Playwright says the agent receives a structured accessibility tree containing elements such as headings, text boxes, list items, and checkboxes. It uses element references to interact with the page.

A successful run should result in Claude Code invoking Playwright browser tools, opening the demonstration site, and adding items. Browser operation may be headless, so the absence of a normal visible browser window does not by itself indicate failure. The repository states that both headless and headed operation are supported on macOS, but it does not provide a Claude Code command here for changing MCP launch mode.

Optional alternative: Playwright CLI for coding agents

Playwright also publishes a separate CLI specifically designed for coding agents, including Claude Code and Copilot. Microsoft describes it as more token-efficient than MCP because commands avoid placing large tool schemas and accessibility trees into model context.

This is an **alternative agent-facing route**, not a required second step for the MCP setup. If you want this route, install the CLI with the repository’s command:

npm install -g @playwright/cli@latest

For richer agent integration, the README documents this optional follow-up:

playwright-cli install --skills

That command installs skills according to the Playwright CLI’s own supported workflow. The supplied files do not specify the exact Claude Code skill directory, generated files, or minimum Claude Code version, so do not manually copy files into guessed locations.

You can then ask Claude Code:

> Test the “add todo” flow on https://demo.playwright.dev/todomvc using playwright-cli. Take screenshots for all successful and failing scenarios.

You may also exercise the CLI directly with these documented commands, entered one at a time:

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli screenshot

The first command opens the demonstration site in a visible browser. The next commands type a todo, press Enter, and take a screenshot.

To open the CLI’s visual session dashboard, use:

playwright-cli show

Playwright says this dashboard displays live screencast previews of running browser sessions. You can select a session, zoom in, and take remote control.

Optional access to an existing signed-in Chrome profile

The repository includes a Playwright Chrome Extension that can connect an AI assistant to pages in your existing browser profile. This grants access to existing cookies, sessions, and logged-in websites, so it is substantially more sensitive than an isolated automation browser.

The documented prerequisites are Chrome, Edge, or Chromium. Install the **Playwright Extension** from the Chrome Web Store link supplied in `packages/extension/README.md`. On first connection, the extension shows a page where you select the browser tab the assistant may reach. Multiple clients receive separate tab groups, and a tab can belong to only one client at a time.

The extension documentation runs the MCP package with an additional `--extension` option, but the supplied files provide that only as a generic JSON MCP-client configuration. They do not provide a corresponding Claude Code `claude mcp add` command. Therefore, this guide does not invent one. Use the basic Claude Code MCP setup above unless you are configuring a client through the documented JSON format.

By default, each browser connection requires your approval. The extension can display a unique `PLAYWRIGHT_MCP_EXTENSION_TOKEN` that bypasses repeated approval, but that token authenticates access to your browser profile. Do not paste it into chat, commit it to a repository, or share it. Manual per-connection approval is the safer layperson choice.

Choosing the right Playwright route

Use **MCP** when you want Claude Code to receive native browser tools and structured page snapshots. This is the repository’s direct, one-command Claude Code setup.

Use **Playwright CLI** when you prefer explicit browser commands and the repository’s stated token-efficiency advantage. Its optional skills add agent guidance.

Use **Playwright Test** only when you are building an end-to-end test project. Its documented project initializer is:

npm init playwright@latest

Use the **Playwright Library** only when writing your own Node.js automation scripts. Its documented installation command is:

npm i playwright

These test and library installations are not required merely to give Claude Code browser tools.

Safety and limitations

Browser automation can click controls, submit forms, alter data, and interact with authenticated accounts. Begin with the public TodoMVC demonstration rather than banking, email, administrative, production, or other sensitive sites. Review consequential actions before allowing them to proceed.

The existing-profile extension has access to the state of tabs you explicitly connect, including logged-in sessions. Keep sensitive tabs out of the client’s tab group and retain the default approval dialog unless you genuinely need unattended connections.

Finally, the supplied repository files do not document uninstall, rollback, Tahoe-specific repair, or Claude Code diagnostic commands. Rather than guessing, consult the first-party Playwright MCP documentation linked from the repository and Claude Code’s first-party MCP documentation if registration fails. The source-supported installation command remains:

claude mcp add playwright npx @playwright/mcp@latest