Playwright MCP ServerPlaywright MCP Server

模型与开放条件Model & openness

本身不调用模型，是被客户端调用的接口实现。 用 Playwright 的无障碍树（accessibility tree）而非像素输入， 因此不需要视觉模型，输出为结构化快照。

It calls no model itself; it is an interface implementation called by clients. It drives Playwright's accessibility tree rather than pixel input, so no vision model is needed and output is structured snapshots.

运行位置Where it runs

本地 Node.js 进程（需 Node.js 18+），通过 stdio 通信。 它也提供 HTTP endpoint 模式。另有浏览器扩展模式（Edge / Chrome）。 默认有头模式，可用 --headless 切换。

A local Node.js process (Node.js 18+ required), communicating over stdio. It also offers an HTTP endpoint mode, plus a browser-extension mode (Edge / Chrome). Headed mode is the default; switch with --headless.

本地文件Local files

无本地文件访问能力。核心能力是浏览器控制。 用户 profile 默认落盘在 Playwright 缓存目录（按 workspace hash 隔离）， 用 --isolated 可改为仅存内存。

No local file-access capability. The core capability is browser control. The user profile is persisted by default in the Playwright cache directory (isolated by workspace hash); --isolated switches it to in-memory only.

关机后的任务Tasks after shutdown

浏览器进程可保持常驻。--idle-timeout 控制空闲关闭： headless 默认 1 小时关闭，headed 模式默认永不关闭； 下次工具调用会重新拉起浏览器。

The browser process can stay resident. --idle-timeout controls idle shutdown: headless closes after 1 hour idle by default; headed mode never closes by default; the next tool call relaunches the browser.

工具与扩展Tools & extensions

它提供完整的浏览器自动化工具集。本站已按官方 README 逐条核对，共 72 个工具 （2026-10-08）：

• 导航与标签页
• 点击 / 拖放 / 悬停
• 表单与键盘输入
• 无障碍树快照（snapshot）
• 截图与 PDF
• 网络请求与路由（route / unroute）
• Cookie 与 localStorage / sessionStorage 读写
• 文件上传
• 对话框处理
• 视频录制与 tracing（start / stop）、以及 verify_* 断言组等

输出以无障碍树结构为主，是结构化数据，可直接消费。

It provides a full browser-automation toolset. This site has checked it item by item against the official README: 72 tools in total (2026-10-08):

• navigation and tabs
• click / drag-and-drop / hover
• forms and keyboard input
• accessibility-tree snapshots
• screenshots and PDF
• network requests and routing (route / unroute)
• reading and writing cookies and localStorage / sessionStorage
• file uploads
• dialog handling
• video recording and tracing (start / stop), plus the verify_* assertion group, etc.

Output is mainly accessibility-tree structure — structured data, ready for direct consumption.

上下文与记忆Context & memory

保持浏览器上下文是本 server 的核心价值—— README 明确指出 MCP 形态适合需要持久状态、 丰富内省与迭代推理的 agentic loop， 例如探索性自动化、自愈测试、长时自主工作流。

Keeping the browser context is this server's core value — the README states explicitly that the MCP form suits agentic loops needing persistent state, rich introspection and iterative reasoning, e.g. exploratory automation, self-healing tests, long-running autonomous workflows.

权限与限制Permissions & limits

需要给浏览器授予权限，且官方明确说明限制手段不是安全边界。

--grant-permissions 可授予 geolocation、clipboard-read、clipboard-write 等权限。

--allowed-origins 与 --blocked-origins 的文档原文明确写着： 「does not serve as a security boundary」且不影响重定向。 默认允许所有来源。

The browser must be granted permissions, and the official docs state plainly that the restriction controls are not a security boundary.

--grant-permissions can grant geolocation, clipboard-read, clipboard-write and similar permissions.

The documentation for --allowed-origins and --blocked-origins states verbatim: "does not serve as a security boundary" and does not affect redirects. All origins are allowed by default.

适合什么任务Best for

需要浏览器自动化且要保持会话状态的场景： 探索性自动化、自愈测试、长时自主工作流。

不适合高吞吐编码 agent——README 自己建议这类场景改用 Playwright CLI + SKILLS，因为 token 效率更高。

Scenarios needing browser automation that must keep session state: exploratory automation, self-healing tests, long-running autonomous workflows.

Not a fit for high-throughput coding agents — the README itself recommends Playwright CLI + SKILLS for those, for better token efficiency.

传输方式Transport

支持 stdio，另提供 HTTP endpoint 模式（--endpoint） 与浏览器扩展连接模式（--extension，需装 Playwright 扩展，仅 Edge / Chrome）。

--shared-browser-context 用于共享浏览器上下文。 多个 HTTP 客户端可共用同一上下文。

Supports stdio, and offers an HTTP endpoint mode (--endpoint) plus a browser-extension connection mode (--extension; requires the Playwright extension, Edge / Chrome only).

--shared-browser-context shares a browser context; multiple HTTP clients can share one context.

认证机制Authentication

stdio 形态无独立认证层，继承客户端用户权限。

HTTP 模式（2026-10-08 核验官方 README）：选项表没有 token / auth 相关参数。Docker 示例直接以 --host 0.0.0.0 裸监听。官方明确声明

“Playwright MCP is not a security boundary”，要求按 MCP 安全最佳 实践自行加固（反向代理 / 网络层）。认证要自己加，别默认它有。

The stdio form has no separate authentication layer; it inherits the client user's permissions.

HTTP mode (official README verified 2026-10-08): the options table has no token/auth parameter. The Docker example listens bare with --host 0.0.0.0. The official docs state plainly

"Playwright MCP is not a security boundary", requiring users to harden it themselves (reverse proxy / network layer) per MCP security best practices. Add authentication yourself; do not assume it exists.

权限范围Permission scope

控制的是浏览器而非文件，但风险面同样宽： 默认允许访问所有来源（--allowed-origins 默认放行全部）， 且可被授予地理位置、剪贴板读写等浏览器权限。

官方明确声明来源限制不是安全边界， 需要真正隔离时应使用 --isolated 或容器化网络策略。

What it controls is the browser, not files — but the risk surface is just as wide: all origins are allowed by default (--allowed-origins allows everything by default), and browser permissions such as geolocation and clipboard read/write can be granted.

The official docs state plainly that origin restrictions are not a security boundary; for real isolation use --isolated or containerized network policies.

Fast and lightweight — Uses Playwright's accessibility tree, not pixel-based input.
LLM-friendly — No vision models needed, operates purely on structured data.
Deterministic tool application — Avoids ambiguity common with screenshot-based approaches.

Fast and lightweight — Uses Playwright's accessibility tree, not pixel-based input.
LLM-friendly — No vision models needed, operates purely on structured data.
Deterministic tool application — Avoids ambiguity common with screenshot-based approaches.

--idle-timeout：空闲多少毫秒后关闭浏览器，下次工具调用会重新拉起。
  headless 默认 1 小时
  headed    默认永不关闭
  0         禁用该行为

--idle-timeout: close the browser after this many ms idle; the next tool call relaunches it.
  headless  defaults to 1 hour
  headed    never closes by default
  0         disables the behaviour

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.