一、安装（三种可选方式）

方式A：MCP 客户端配置（推荐，自动拉取最新）

在 Cursor、VS Code、Claude Desktop 等客户端的 mcpServers 配置中添加：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

客户端首次连接时会自动下载并缓存，无需手动安装。

方式B：命令行直接运行（测试 / 独立使用）

npx @playwright/mcp@latest

适合在终端直接启动 MCP 服务，验证工具可用性或配合自定义客户端。

方式C：全局安装（可选）

npm install -g @playwright/mcp
playwright-mcp

全局安装后可省去每次 npx 的下载延迟，但需自行管理版本。

二、配置 AI Agent（连接 MCP 客户端）

Playwright MCP 支持主流 AI 编码助手/编辑器，只需在对应的配置文件中加入 MCP 服务声明。

标准 JSON 配置模板

{
  "type": "stdio",
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--browser=chrome",
    "--isolated",
    "--caps=vision,pdf,devtools,network,testing"
    ...
  ]
}

各客户端配置位置速查

Cursor：.cursor/mcp.json 或通过设置界面 MCP > Add new MCP server
VS Code / VS Code Insiders：.vscode/mcp.json 或使用 “MCP Server Manager” 扩展
Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Windsurf：.windsurf/mcp.json
Copilot / Cline / Junie 等：参照各自 MCP 配置指引，均使用相同的 JSON 格式。

三、服务器启动与核心参数

基本启动

npx @playwright/mcp@latest

常用命令行参数

所有参数均可写入 args 数组（客户端配置）或直接用于命令行启动。

参数	环境变量	说明
`--browser <browser>`	`PLAYWRIGHT_MCP_BROWSER`	浏览器类型：`chrome`, `firefox`, `webkit`, `msedge`
`--headless`	`PLAYWRIGHT_MCP_HEADLESS`	无头模式运行（默认有头）
`--isolated`	`PLAYWRIGHT_MCP_ISOLATED`	隔离会话，关闭浏览器后清空存储状态
`--storage-state <path>`	`PLAYWRIGHT_MCP_STORAGE_STATE`	加载 cookies/localStorage 文件（配合 `--isolated` 使用）
`--user-data-dir <path>`	`PLAYWRIGHT_MCP_USER_DATA_DIR`	浏览器用户数据目录（持久化登录状态）
`--allowed-hosts <hosts>`	`PLAYWRIGHT_MCP_ALLOWED_HOSTS`	允许访问的主机列表，逗号分隔，默认同绑定主机
`--ignore-https-errors`	`PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS`	忽略 HTTPS 证书错误
`--port <port>`	`PLAYWRIGHT_MCP_PORT`	SSE/HTTP 传输端口，用于独立部署
`--host <host>`	`PLAYWRIGHT_MCP_HOST`	绑定地址，默认 `localhost`；`0.0.0.0` 接受所有来源
`--config <path>`	`PLAYWRIGHT_MCP_CONFIG`	指定 JSON 配置文件
`--caps <capabilities>`	`PLAYWRIGHT_MCP_CAPS`	启用扩展能力：`vision`,`pdf`,`devtools`,`config`,`network`,`storage`,`testing`
`--timeout-action <ms>`	`PLAYWRIGHT_MCP_TIMEOUT_ACTION`	操作超时毫秒，默认 5000
`--timeout-navigation <ms>`	`PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION`	导航超时毫秒，默认 60000
`--init-page <path>`	`PLAYWRIGHT_MCP_INIT_PAGE`	页面初始化 TypeScript 脚本
`--init-script <path>`	`PLAYWRIGHT_MCP_INIT_SCRIPT`	注入到每个页面的 JavaScript 脚本

查看完整参数列表：

npx @playwright/mcp@latest --help

四、会话与浏览器配置

持久化用户档案（默认模式）

默认使用持久化用户数据目录，保持登录状态和本地存储，适合长期运行的 Agent。

各平台目录位置（自动基于工作区哈希生成）：

Windows: %USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-{workspace-hash}
macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}
Linux: ~/.cache/ms-playwright/mcp-{channel}-{workspace-hash}

同一工作区不可同时运行多个持久化实例，需并行时请使用 --isolated 或指定不同的 --user-data-dir。

隔离会话（推荐用于测试）

每次调用关闭浏览器后，所有存储状态将丢失，保证测试隔离性。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state=./state.json"
      ]
    }
  }
}

--storage-state 用于预置 cookies/localStorage（可通过 Playwright 脚本生成）。

连接已有浏览器（Extension 模式）

安装 “Playwright MCP Extension” 后，可通过 --extension 连接已打开的 Chrome/Edge 标签页，直接复用登录态和浏览器状态。详见 Extension 安装说明。

五、工具集与功能（Capabilities）

默认已包含核心自动化、标签管理、浏览器安装等工具。部分高级功能需通过 --caps 显式启用。

核心工具（始终可用）

browser_navigate：导航到 URL
browser_click：点击元素
browser_type：文本输入
browser_snapshot：获取可访问性树快照（无需截图）
browser_take_screenshot：截图（需显式调用）
browser_evaluate：执行 JavaScript
browser_run_code：生成并运行 Playwright 代码片段（默认 TypeScript）

可选 Capabilities

能力	参数	说明
视觉坐标模式	`--caps=vision`	启用基于坐标的点击/滚动（适用于无障碍树无法捕获的场景）
PDF 生成	`--caps=pdf`	添加 `browser_pdf` 工具
DevTools 网络	`--caps=devtools`	暴露 CDP 网络相关操作
网络控制	`--caps=network`	拦截/修改网络请求
存储操作	`--caps=storage`	管理 cookies、localStorage、indexedDB
配置管理	`--caps=config`	运行时修改浏览器上下文配置
测试断言	`--caps=testing`	提供 `expect` 风格断言工具

启用多个能力：

npx @playwright/mcp@latest --caps=vision,pdf,network

六、独立服务器部署（HTTP 传输）

在无显示环境的机器上运行有头浏览器，或从 IDE 工作进程访问时，建议以 HTTP 模式启动：

npx @playwright/mcp@latest --port 8931 --host 0.0.0.0

客户端配置改为 url 形式：

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

七、版本升级与固定版本

始终使用最新版

客户端配置中保留 @playwright/mcp@latest，每次重启自动拉取最新。

固定特定版本

替换 @latest 为具体版本号：

"args": ["@playwright/mcp@0.0.1"]

手动升级全局安装

npm update -g @playwright/mcp

八、开发者源码构建 & 测试（从源码贡献）

获取仓库

git clone https://github.com/microsoft/playwright-mcp.git
cd playwright-mcp

构建与运行

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 直接从源码运行
node packages/mcp/dist/index.js

# 或使用 npx 指向本地
npx .@latest

测试

npm test

详细贡献指南请参考项目 CONTRIBUTING.md。

九、完整卸载（清理配置与缓存）

步骤1：移除 MCP 客户端配置

从对应客户端的配置文件中删除 playwright 条目：

Cursor：编辑 .cursor/mcp.json
VS Code：编辑 .vscode/mcp.json
Claude Desktop：编辑 claude_desktop_config.json

步骤2：清理浏览器用户数据（可选）

持久化配置文件会占用磁盘，可在手动删除：

Windows：删除 %USERPROFILE%\AppData\Local\ms-playwright\mcp-*
macOS/Linux：删除 ~/Library/Caches/ms-playwright/mcp-* 或 ~/.cache/ms-playwright/mcp-*

步骤3：卸载全局 NPM 包（若通过方式C安装）

npm uninstall -g @playwright/mcp

步骤4：清理 npx 缓存（可选）

npx clear-npx-cache
# 或手动删除 ~/.npm/_npx/

Playwright MCP 安装与配置