You want an AI assistant (Claude Code/Cursor/Codex or any MCP-capable agent) to actually operate a browser: open pages, click, fill forms, scrape content, run tests — instead of only giving advice. playwright-mcp is the official MCP server from the Playwright project: it wraps Playwright's browser capabilities into MCP tools, and the agent drives real Chromium through the standard MCP protocol.

Use it when:

• Your agent needs browser operations (form filling/posting/cross-page tasks);
• You want AI-driven web automation testing/scraping;
• You need the browser execution layer of combo-auto-test (deepcode + swe-rex + playwright-mcp).

Don't use it when: you only need manual human browser testing (use Playwright scripts directly); you only need to curl pages (no browser rendering required).

China network reality: the npm package itself works through the npmmirror registry; the first launch downloads the browser engine (chromium ~114MiB). Newer builds (server 1.63 series) use the chrome-for-testing layout, which npmmirror does not mirror yet (404 measured); the official CDN was measured working in ~1 minute (2026-09-01, see Section 5).

# Source: Trove detailed guide · verified 2026-08-29
npm_config_registry=https://registry.npmmirror.com npm install -g @playwright/mcp
npx --no-install @playwright/mcp --port 8931 --headless

Expected output: Listening on http://localhost:8931 (point the client url at the /mcp endpoint; measured 2026-08-29)

Prerequisites: Node ≥ 18 (Node 24.15.0 measured here). First launch downloads chromium (~114MiB) automatically; if the download is slow, use PLAYWRIGHT_DOWNLOAD_HOST (Section 5).

Verify after install:

• the server listens on 8931;
• curl /mcp returns non-200 (rejecting illegal GET is expected security behavior);
• the headless smoke test opens a page (operation 3 in Section 5).

Install variants (deep dive)

npm-global @playwright/mcp + first-run browser engine download (chromium 113.9MiB); npx --no-install @playwright/mcp --port 8931 --headless starts the MCP server (HTTP+SSE), and the client configures the endpoint in its MCP config. The no-install form npx -y @playwright/mcp@latest is officially supported.

Key concepts:

• MCP server: browser control service (HTTP+SSE, default 8931);
• --headless: headless mode (works on servers);
• workspace roots / allowed-hosts: default security boundary.

What it touches after install: writes no project/user config; the browser engine cache lands in ~/.cache/ms-playwright; runtime browser profiles default to temp dirs, not persisted.

Step 1: start the MCP server (HTTP+SSE mode)

# Source: Trove detailed guide · verified 2026-08-29
npx --no-install @playwright/mcp --port 8931 --headless

Expected output: Listening on http://localhost:8931 (point the client url at the /mcp endpoint; measured 2026-08-29)

If stuck:

• npx says not found → globally installed but npx --no-install cannot find it; check the npm global bin is on PATH;
• port taken → use --port with another port;
• "Chromium distribution chrome is not found" → the default is the chrome channel; use \--browser chromium\ for the bundled engine (measured 2026-09-01);
• "Access to file: protocol is blocked" → file:// navigation is blocked by default (security boundary); use http:// or add --allow-unrestricted-file-access.

Step 2: verify the server is alive

# Source: Trove detailed guide · 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; only POST JSON-RPC is accepted — root path 403 measured 2026-08-29)

If stuck:

• 000/connection refused → the server is not running; see Step 1;
• 200 → abnormal (an MCP endpoint should reject GET); check whether another service occupies 8931.

Step 3: headless browser smoke test (verify the browser engine works)

# Source: Trove detailed guide · verified 2026-08-29
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 (measured 2026-08-29)

If stuck:

• browser not installed → the first launch failed to download the engine; run npx playwright install chromium manually or reinstall with PLAYWRIGHT_DOWNLOAD_HOST;
• slow/failed download → PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright npx playwright install chromium (domestic mirror path, measured approach).

Step 4: connect a client

Explanation: configure the endpoint in an MCP-capable client (example: Claude Code mcp config).

# Source: Trove detailed guide · verified 2026-08-29
# example (client config, not a command): url=http://localhost:8931/mcp, transport=http

Expected output: the client's MCP tool list shows playwright tools (browser_navigate/click/fill_form etc.; connection succeeded 2026-08-29, protocol-level re-test 2026-09-01: initialize handshake + tools/list enumerating 20+ tools, evidence in Section 10)

If stuck:

• client cannot connect → confirm the server is running and the url uses the /mcp endpoint (not the root path);
• "Access is only allowed at localhost:8931" → the server validates the Host header; the url must use localhost, not 127.0.0.1 (measured 2026-09-01);
• tools missing → restart the client's MCP connection.

Same source as the tool-page matrix; full pairs, status and evidence at conflict matrix (co-install). Known relations:

• deepcode/swe-rex × playwright-mcp: members of combo-auto-test (automation test execution layer), complementary;
• browser-use (not collected): adjacent browser-automation positioning — moderate demand-signal overlap (E2 round: not adopting for now);
• Others: write surfaces do not overlap (~/.cache/ms-playwright + temp profiles), statically judged co-installable.

• Symptom: launch says browser not installed → first engine download failed; run npx playwright install chromium or reinstall with PLAYWRIGHT_DOWNLOAD_HOST
• Symptom: curl /mcp returns 403 → normal (rejects illegal GET); only POST JSON-RPC is accepted
• Symptom: client cannot connect → confirm the server is running and the url uses the /mcp endpoint (Host must be localhost; 127.0.0.1 yields "Access is only allowed at localhost:8931", measured)
• Symptom: npx cannot find the package → the global bin is not on PATH
• Symptom: slow engine download → PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright (domestic mirror)

Full four-section entries (symptom→cause→fix→evidence): site docs (if recorded)

# Source: Trove detailed guide · verified 2026-08-29
npm uninstall -g @playwright/mcp --no-audit --no-fund && rm -rf ~/.cache/ms-playwright

Expected output: npm removal output (Removed N packages); ~/.cache/ms-playwright absent = clean

Note: the engine cache is ~114MiB; before deleting, confirm no other Playwright project uses the same cache.

• Q: Is curl /mcp returning 403 a problem? A: No. The MCP endpoint only accepts POST JSON-RPC; rejecting GET is expected security behavior (measured).
• Q: Slow browser engine download? A: Point PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright at the domestic mirror and reinstall.
• Q: Does headless mode work? A: Yes, --headless measured working (usable on servers).
• Q: Overlaps with browser-use? A: Adjacent positioning, but playwright-mcp is the official MCP server and is collected; browser-use has medium demand-signal overlap and is not adopted (E2 decision).
• Q: Where do I report issues? A: install/uninstall issues go through this entry's feedback; project issues go to the author repo.

• Version: 1.x (manifest range; measured 2026-08-29).
• Environment: Node ≥18 (24.15.0 measured); browser engine cache ~/.cache/ms-playwright (~114MiB).
• Network: npm via npmmirror; engine download can use PLAYWRIGHT_DOWNLOAD_HOST domestic mirror.
• Write surface: ~/.cache/ms-playwright + temp profiles; no project/user config.
• Port: 8931 (default).

• Sources: official project docs (English README/docs) + local measurements (2026-08-29/30)
• Entry signature: microsoft/playwright-mcp (official MCP server, kept as-is)

• Measured: `site docs (2026-08-29: npm install + engine download + MCP server start Listening + curl /mcp 403 security behavior + headless smoke ok; 2026-08-30 usage measurements reinforced)
• Not tested: complex interaction automation against real business sites (this run covered a local test page end to end); no-install npx form; Windows/macOS forms.

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方 README（npm registry readme 字段，v0.0.79）：Playwright MCP 完整用法 [官方文档 · Playwright 官方 · 2026-08-31（包 0.0.79）]
  官方用法全解——MCP 服务器接入（Claude/其他客户端）、启动方式（CLI / npx / 独立服务器）、配置（浏览器/能力开关 vision/pdf/devtools、用户目录、启动页）、跨平台（Windows/macOS/Linux）、VS Code 集成、standalone server 形态、与 Playwright CLI 的边界