playwright-mcp

What you will run into

You want an AI agent to actually drive a browser — navigate, click, assert, extract — Playwright MCP exposes real browser control to agents via an MCP server. The two things people trip on: installation is two steps, not one — the npm package (installs in seconds) AND the browser engine (chromium 113.9MiB, mandatory first download), so "server won't start" usually means the engine is missing; and the server only accepts POST JSON-RPC — a plain GET on /mcp returns non-200 (403 verified), which is expected, not a bug. When to use it:

• Letting agents navigate/click/assert in a real browser;
• Web deploy verification (combo combo-web-deploy-verify);
• Local browser automation against your own pages.

When not to use it: you only need HTTP-level checks (curl is enough); or you cannot accept the ~114MiB engine cache.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

npm package @playwright/mcp (global install; Node >= 18) + separate browser engine download npx --no-install playwright install chromium (113.9MiB, cached in ~/.cache/ms-playwright/). Start the server with --port 8931 --headless (--headless for GUI-less servers); clients point at http://localhost:8931/mcp. Security defaults: file access limited to workspace roots, navigation limited to allowed-hosts; sensitive switches like --allow-unrestricted-file-access must be explicitly enabled. Key concepts:

• engine: chromium 113.9MiB, mandatory first download, cached;
• endpoint: http://localhost:8931/mcp (POST JSON-RPC only);
• headless: no-GUI mode (verified on a headless shell).

Where it writes: no project/user config writes; engine cache + temp profile.

Step by step

Step 1: Install the npm package + browser engine (why two steps: the engine is 113.9MiB, mandatory on first install)

Why: the npm package itself installs in seconds (verified 2026-08-29); the chromium engine (113.9MiB) is a separate mandatory download. Mainland npm: use the npmmirror prefix.

npm_config_registry=https://registry.npmmirror.com npm install -g @playwright/mcp
npx --no-install @playwright/mcp --version

Expected output: Version 0.0.79

npx --no-install playwright install chromium

Expected output: browser engine download complete (verified 2026-08-29) After install, confirm:

• --version prints 0.0.79;
• the engine download completes without errors.

Stuck? How to recover:

• npm slow → confirm the npmmirror prefix;
• engine download fails → retry; confirm disk space (~114MiB cache);
• Node version → confirm >= 18.

Step 2: Start the MCP server and verify (verified here)

Why: --port 8931 --headless starts the server (--headless for GUI-less servers). Clients configure the url to point at the /mcp endpoint; the server only accepts POST JSON-RPC, and a GET returning non-200 is expected security behavior.

npx --no-install @playwright/mcp --port 8931 --headless --browser chromium

Expected output: Listening on http://localhost:8931 (clients configure the url to point at the /mcp endpoint; verified 2026-08-29)

curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8931/mcp

Expected output: non-200 (rejecting illegal GET is expected security behavior; POST JSON-RPC is accepted — root path 403 verified 2026-08-29) After install, confirm:

• the startup log shows Listening;
• curl returns non-200 (403 is expected).

Stuck? How to recover:

• port taken → change --port;
• startup failed → confirm the engine is installed (step 1).

Step 3: Headless browser smoke (self-check the engine, verified here)

Why: launching chromium headless directly via the playwright library and reading a page title confirms the engine works — if this passes, the browser path is fine and MCP issues are not in this layer.

node -e "const {chromium}=require('@playwright/mcp/node_modules/playwright');(async=>{const b=await chromium.launch({headless:true});const p=await b.newPage;await p.goto('data:text/html,<title>ok</title>');console.log(await p.title);await b.close})"

Expected output: ok (verified 2026-08-29) Stuck? How to recover:

• require path not found → confirm the engine is installed (step 1) and the package path did not change;
• launch fails → confirm --headless mode and system dependencies (verified on a headless shell).

How to confirm it works

Step 1: Confirm the package and engine are in place

Why: --version printing 0.0.79 confirms the npm package; the engine is a separate download (113.9MiB) — a missing engine makes startup fail.

npx --no-install @playwright/mcp --version

Expected output: Version 0.0.79 Stuck? How to recover:

• version mismatch → reinstall the npm package;
• engine missing → run npx --no-install playwright install chromium.

Step 2: Start + headless browser smoke

Why: the server Listening and the headless browser opening a page and reading the title confirm both the MCP surface and the browser path.

npx --no-install @playwright/mcp --port 8931 --headless --browser chromium

Expected output: Listening on http://localhost:8931 (clients configure the url to point at the /mcp endpoint)

node -e "const {chromium}=require('@playwright/mcp/node_modules/playwright');(async=>{const b=await chromium.launch({headless:true});const p=await b.newPage;await p.goto('data:text/html,<title>ok</title>');console.log(await p.title);await b.close})"

Expected output: ok (verified 2026-08-29) Stuck? How to recover:

• require path not found → confirm the engine is installed and the package path did not change;
• launch fails → confirm --headless mode and system dependencies.

Other environments

• Machines with a GUI: drop --headless to watch the real browser operate (verified on a headless shell).
• Windows / macOS: npm install and start commands are the same (npmmirror prefix still recommended domestically); engine cache at ~/.cache/ms-playwright.
• Port: default 8931, changeable with --port; switch when taken.
• Security: default file access limited to workspace roots, navigation limited to allowed-hosts; sensitive switches like --allow-unrestricted-file-access must be explicitly enabled.

Daily usage

Startup and entry

• MCP server: npx --no-install @playwright/mcp --port 8931 --headless --browser chromium;
• Clients: endpoint http://localhost:8931/mcp.

Common operations

Operation 1: Start the MCP server (HTTP+SSE mode)

npx --no-install @playwright/mcp --port 8931 --headless --browser chromium

Expected output: Listening on http://localhost:8931 (clients configure the url to point at the /mcp endpoint; verified 2026-08-29) Operation 2: Verify the server is alive

curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8931/mcp

Expected output: non-200 (rejecting illegal GET is expected security behavior; POST JSON-RPC is accepted — root path 403 verified 2026-08-29) Operation 3: Headless browser smoke (self-check the engine)

node -e "const {chromium}=require('@playwright/mcp/node_modules/playwright');(async=>{const b=await chromium.launch({headless:true});const p=await b.newPage;await p.goto('data:text/html,<title>ok</title>');console.log(await p.title);await b.close})"

Expected output: ok (verified 2026-08-29)

Data and directories

• Browser engine cache: ~/.cache/ms-playwright/ (~114MiB);
• Runtime profile: temp directory, not persisted.

Uninstall & cleanup

note: npm global uninstall + command-surface verification; the ~/.cache/ms-playwright engine cache is optionally deletable

npm uninstall -g @playwright/mcp
command -v @playwright/mcp >/dev/null 2>&1 && echo "残留: playwright-mcp 仍存在" || echo "playwright-mcp removed: OK"

Expected output: playwright-mcp removed: OK Manual checklist (for full cleanup):

• ~/.cache/ms-playwright/ (browser engine cache, ~114MiB; delete the matching version directory)
• a running MCP server process (default port 8931, check with lsof -i :8931)

Dependency warnings

• Version: [0.0.79, 0.0.79] locked (verified 2026-08-29).
• Environment: Node >= 18; browser engine chromium 113.9MiB (mandatory first download, cached at ~/.cache/ms-playwright); use --headless without a GUI.
• Network: npm via npmmirror prefix (verified seconds-level install 2026-08-29).
• Port: default 8931 (--port changeable).
• Security: default file access limited to workspace roots, navigation limited to allowed-hosts; sensitive switches like --allow-unrestricted-file-access must be explicitly enabled.
• Write surface: no project/user config writes; engine cache + temp profile.
• Co-install: with vite-deploy judged possible-compatible (deploy writes build artifacts, verification writes browser state; no write-surface overlap); combo "web deploy verification": site docs.

FAQ

• Q: Will it change my config? A: no project/user config writes; the browser engine cache goes to ~/.cache/ms-playwright; runtime browser profiles are temp directories, not persisted.
• Q: Security boundary? A: default file access limited to workspace roots, navigation limited to allowed-hosts; sensitive switches like --allow-unrestricted-file-access must be explicitly enabled (confirmed via help surface 2026-08-29).
• Q: Can a GUI-less server environment use it? A: yes, --headless mode (chromium headless shell smoke verified 2026-08-29).
• Q: Use with vite-deploy? A: judged possible-compatible — deploy (build artifacts) and verification (browser) write surfaces do not overlap, co-install not tested; combo "web deploy verification": site docs.
• Q: Can't npm install domestically? A: use the npmmirror prefix from the install section (verified seconds-level install 2026-08-29).
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.