Playwright MCP v Dockeru na Alpine Linux / ARM64

Vytvořeno: 5.5.2026 | Aktualizováno: 05.05.2026 11:31

Playwright MCP (`@playwright/mcp`) je MCP server, který AI umožňuje ovládat webový prohlížeč — navigovat stránky, klikat, vyplňovat formuláře nebo pořizovat screenshoty.

Pouze pro Alpine Linux / ARM64: Na amd64 s běžnou distribucí (Ubuntu, Debian, Fedora) standardní konfigurace funguje bez úprav — Playwright stáhne bundled Chromium automaticky. Tento postup je potřeba jen při kombinaci Alpine Linux (musl libc) + ARM64 + Docker bez `SYS_ADMIN` capability.

Proč to nefunguje ve výchozí konfiguraci

Playwright při startu stáhne nebo spustí vlastní bundled Chromium. Na Alpine (musl libc) a ARM64 to selže ze dvou důvodů:

Bundled Chromium je zkompilovaný proti glibc — na Alpine (musl) nespustíš, bez ohledu na architekturu
Docker kontejner bez capability SYS_ADMIN nemá povolený namespace sandbox — Chromium padá s Failed to move to new namespace: Operation not permitted

Řešení jsou dvě části:

Použít systémový chromium instalovaný přes apk add chromium místo bundled
Vytvořit wrapper skript, který injectuje –no-sandbox flagy — ty nelze předat přes parametr –executable-path Playwright MCP přímo

Příprava systémového Chromia

Na Alpine nainstaluj Chromium přes apk:

apk add chromium

Chromium se nainstaluje do /usr/bin/chromium (symlink na /usr/lib/chromium/chromium-launcher.sh). Ověř:

chromium --version
# Chromium 147.x.x Alpine Linux

Wrapper skript

Playwright předává spustitelný soubor přes –executable-path, ale sandbox flagy tak předat nelze. Wrapper skript pouští systémový chromium s potřebnými flagy a předává mu všechny ostatní argumenty od Playwright.

Vytvoř soubor /home/aiwork/tools/chromium-wrapper/chromium-mcp-wrapper.sh:

#!/bin/sh
exec /usr/bin/chromium --no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage "$@"

Nastav spustitelná práva:

chmod +x /home/aiwork/tools/chromium-wrapper/chromium-mcp-wrapper.sh

Co jednotlivé flagy dělají:

–no-sandbox — zakáže Chrome sandbox, který v Dockeru bez SYS_ADMIN capability padá
–disable-setuid-sandbox — zakáže setuid sandbox (záloha k –no-sandbox)
–disable-dev-shm-usage — Chromium místo /dev/shm použije tmp; /dev/shm může být v Dockeru omezený
„$@“ — předá všechny argumenty od Playwright dál do Chromia

Konfigurace pro Claude Code

Do ~/.claude.json do sekce mcpServers přidej (nebo uprav existující záznam playwright):

"playwright": {
  "type": "stdio",
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--isolated",
    "--headless",
    "--browser",
    "chrome",
    "--executable-path",
    "/home/aiwork/tools/chromium-wrapper/chromium-mcp-wrapper.sh",
    "--storage-state=/home/aiwork/tools/playwright-storage/storage.json"
  ],
  "env": {
    "PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD": "1"
  }
}

Oproti standardní konfiguraci jsou klíčové tyto změny:

–browser chrome — Playwright spustí browser jako Chrome kanál, ne bundled chromium
–executable-path — přesměruje spouštění na wrapper (ne přímo na /usr/bin/chromium, který by sandboxem padl)
–headless — nutné v Dockeru bez X serveru
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 — pojistka, aby se Playwright ani nepokusil o download

Konfigurace pro OpenCode

Do ~/.config/opencode/opencode.json do sekce mcp přidej nebo uprav existující záznam playwright:

"playwright": {
  "type": "local",
  "command": [
    "npx",
    "@playwright/mcp@latest",
    "--isolated",
    "--headless",
    "--browser",
    "chrome",
    "--executable-path",
    "/home/aiwork/tools/chromium-wrapper/chromium-mcp-wrapper.sh",
    "--storage-state=/home/aiwork/tools/playwright-storage/storage.json"
  ],
  "environment": {
    "PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD": "1"
  },
  "enabled": true
}

Oproti standardní konfiguraci jsou klíčové stejné změny jako u Claude Code — přidání –browser chrome, –executable-path na wrapper, –headless a env proměnná PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1.

Ověření

Funkčnost lze ověřit přímým MCP voláním před restartem — pošli inicializaci a browser_navigate přes stdin:

cd /tmp && (
  printf '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}\n'
  printf '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"browser_navigate","arguments":{"url":"https://example.com"}}}\n'
  sleep 10
) | PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npx @playwright/mcp@latest \
    --headless --browser chrome \
    --executable-path /home/aiwork/tools/chromium-wrapper/chromium-mcp-wrapper.sh \
    --isolated

Pokud druhá JSON odpověď obsahuje Page URL: https://example.com/ a Page Title: Example Domain, vše funguje.

Po ověření restartuj Claude Code (nebo zadej /exit a znovu spusť) nebo OpenCode, aby načetly nový MCP server. V Claude Code pak /mcp ukáže playwright v seznamu.

Vztah k standardní konfiguraci

Funkčně jde o ekvivalentní náhradu. @playwright/mcp@latest je pořád stejný MCP server, který řídí Chromium přes CDP (Chrome DevTools Protocol). Všechny tooly (browser_navigate, browser_click, browser_snapshot atd.) jsou identické.

Co se liší pouze na Alpine/ARM64:

	Standardní (amd64, glibc)	Tento setup (Alpine, ARM64, Docker)
Chromium	Playwright stáhne bundled build do `~/.cache/ms-playwright/`	Systémový `/usr/bin/chromium` z apk
Sandbox	Funguje standardně	Musí být vypnutý (`–no-sandbox`) přes wrapper
`–executable-path`	Nepotřeba	Povinný — směruje na wrapper
`PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD`	Nepotřeba	Nutné nastavit na `1`
`–headless`	Volitelný	Povinný (bez X serveru)

Drobný rozdíl: verze Chromia. Playwright normálně používá přesně pinnou verzi (standardně 131–137), tady se používá to, co je v Alpine repo (v3.23: verze 147). Pro běžné úkoly jako navigace, klikání, scraping nebo screenshoty je to bez praktického rozdílu.

Obsah