====== Playwright MCP v Dockeru na Alpine Linux / ARM64 ======

//Vytvořeno: **5.5.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/microsoft/playwright-mcp|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:

<code bash>
apk add chromium
</code>

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

<code bash>
chromium --version
# Chromium 147.x.x Alpine Linux
</code>

===== 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'':

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

Nastav spustitelná práva:

<code bash>
chmod +x /home/aiwork/tools/chromium-wrapper/chromium-mcp-wrapper.sh
</code>

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''):

<code json>
"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"
  }
}
</code>

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'':

<code json>
"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
}
</code>

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:

<code bash>
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
</code>

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.

===== Zdroje =====

  * [[https://github.com/microsoft/playwright-mcp|playwright-mcp – GitHub]]
  * [[https://playwright.dev/|Playwright – dokumentace]]