Setting up Playwright MCP Server for Claude Code on Arch Linux

This guide covers setting up the Playwright MCP server for Claude Code on Arch Linux and CachyOS. Playwright MCP does not officially support Arch Linux, so this guide uses Playwright's bundled Chromium build as a workaround.

Prerequisites

Install Node.js and npm:

sudo pacman -S nodejs npm

Verify installation:

node --version
npm --version

The Problem

The Playwright MCP server defaults to using Chrome at /opt/google/chrome/chrome, which does not exist on Arch Linux. The official installer displays an "OS not officially supported" warning and falls back to Ubuntu dependencies.

The Solution

Use Playwright's bundled Chromium build with an explicit executable path.

Step 1: Install Playwright's Chromium

npx playwright install chromium

This downloads approximately 280MB (Chromium, FFMPEG, and headless shell) to ~/.cache/ms-playwright/. The Ubuntu warning can be safely ignored.

Step 2: Locate the Chromium executable

find ~/.cache/ms-playwright -name "chrome" 2>/dev/null

Expected output:

/home/youruser/.cache/ms-playwright/chromium-1194/chrome-linux/chrome

Note: The version number (1194) will vary based on the Playwright release.

Step 3: Configure Claude Code MCP

Add the Playwright MCP server with the full executable path:

claude mcp add --transport stdio playwright -- npx -y @playwright/mcp --browser chromium --executable-path /home/youruser/.cache/ms-playwright/chromium-1194/chrome-linux/chrome --headless

Replace youruser and the version number (chromium-1194) with your actual values from Step 2.

Important: After adding the MCP server, you must restart Claude Code for the changes to take effect.

Step 4: Verify Configuration

claude mcp list

Expected output:

playwright: npx -y @playwright/mcp --browser chromium ... - ✓ Connected

Testing

Test the installation by requesting browser automation tasks such as navigating to websites or taking screenshots.

Troubleshooting

"Browser specified in your config is not installed"

• Verify Chromium installation: npx playwright install chromium
• Check executable path exists: ls ~/.cache/ms-playwright/chromium-*/chrome-linux/chrome

"chromium not found"

• Ensure the --executable-path flag is included in the configuration
• The MCP server defaults to /opt/google/chrome/ which does not exist on Arch Linux

Chromium version updates

When Playwright updates, the version number in the path changes (e.g., chromium-1194 → chromium-1195). Update the MCP configuration:

claude mcp remove playwright
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp --browser chromium --executable-path /home/youruser/.cache/ms-playwright/chromium-XXXX/chrome-linux/chrome --headless

Tested on CachyOS with kernel 6.17.7.