Luke Davis
← Back to blog

Playwright MCP

claude-code mcp playwright ai browser-automation arch-linux wayland web-dev

One of the many features that make agents so wonderful in my opinion is that when an agent runs a command, it’s IN the loop. No need to copy and paste error codes or outputs, the agent sees the output immediately. But this wonderful feature falls off for web development when you need to see browser console errors, or the html generated by react and other JS frameworks.

from familiar to essential

Playwright is a tool many web developers recognized long before the AI boom, but until then, browser automation was a false peak for a lot of people.

Too brittle, inconsistent, hard to use… browser automation, from my perspective felt dead; something you did if you had a tiny project or wanted to get a few thousand views on a YouTube tutorial.

No longer. Thanks to the Playwright MCP server your agents have even more skill. To get started, run this BEFORE you run claude:

claude mcp add playwright npx '@playwright/mcp@latest'

arch linux and omarchy users

If you’re on Arch Linux (or Omarchy), you’ll hit a wall. The default config looks for Google Chrome at /opt/google/chrome/chrome, which doesn’t exist on most Arch systems. You’ll see an error like:

Error: browserType.launchPersistentContext: Chromium distribution 'chrome' is not found at /opt/google/chrome/chrome

Even though you have Chromium installed at /usr/bin/chromium, Playwright doesn’t use your system browser. It manages its own browser versions - separate downloads that live in ~/.cache/ms-playwright/. This gives Playwright consistent behavior across machines, but it means you need to download their version even if you already have a browser installed.

Here’s how to fix it:

1. Reconfigure the MCP server to use chromium:

claude mcp remove playwright # if already run
claude mcp add playwright -- bunx @playwright/mcp@latest --browser chromium

2. Install Playwright’s managed Chromium:

bunx playwright install chromium

You’ll see warnings about your OS not being “officially supported” and it downloading an Ubuntu fallback build. That’s fine. It works.

BEWARE: your OS is not officially supported by Playwright; downloading fallback build for ubuntu24.04-x64.
Downloading Chromium 143.0.7499.4 (playwright build v1200)...

3. Initialize the browser in Claude Code:

Start a new Claude Code session and run the browser_install tool through the MCP. After that, navigation tools like browser_navigate will work.

The MCP config lives in ~/.claude.json under the per-project mcpServers section.

wayland users

If you’re on a pure Wayland setup (Hyprland, Sway, etc.), you’ll hit another issue: the browser runs headless even though headed mode is the default. You can take screenshots and interact with pages, but no browser window ever appears.

The root cause is in Playwright’s config logic:

// playwright/lib/mcp/browser/config.js
headless: import_os.default.platform() === "linux" && !process.env.DISPLAY

On pure Wayland, DISPLAY is empty - you have WAYLAND_DISPLAY instead. Playwright doesn’t check for it, so it assumes there’s no display and defaults to headless.

The fix is to set DISPLAY=:0 in the MCP environment (to satisfy the check) and use your system chromium (which has Wayland support built-in):

claude mcp add -s user playwright \
  --env DISPLAY=:0 \
  --env WAYLAND_DISPLAY=wayland-1 \
  --env XDG_SESSION_TYPE=wayland \
  -- bunx @playwright/mcp@latest --executable-path /usr/bin/chromium

The -s user flag makes the config global across all projects. The fake DISPLAY=:0 tricks Playwright’s headed mode check, while chromium still uses Wayland via its built-in --ozone-platform=wayland flag.

Restart Claude Code after running this command, then verify with claude mcp get playwright.