---
title: "W07 工具说明：Playwright MCP"
---

# Playwright MCP

## 项目介绍

**它是什么。**微软开源的 MCP 服务器，给智能体一个它能操作的浏览器：打开网页、读页面结构、填搜索框、点按钮、翻页、下载、截图。用来处理“直接读网页读不到”的情况：页面打开后才由脚本生成内容、要点按钮才翻页、直接请求返回 403。

MCP（Model Context Protocol）是一套让智能体接外部工具的通用约定：工具按这套约定写成“服务器”，Claude Code、WorkBuddy 这类客户端按同样的写法就能接上。

| 项 | 内容 |
| --- | --- |
| 开发与维护 | 微软 Playwright 团队（GitHub 组织 microsoft） |
| 开源与许可证 | 开源，Apache-2.0 |
| 首次发布 | npm 包 `@playwright/mcp` 首个版本 2025-03-13；GitHub 仓库建于 2025-03-21 |
| 最新版本 | 0.0.83，2026-09-28 |
| GitHub 星数与最近提交 | 38,357 星；默认分支最近一次提交 2026-10-08，最近推送 2026-10-16（2026-10 核查） |
| 接入方式 | MCP（本地 stdio 服务器，Node.js 程序）。Claude Code 和 WorkBuddy 都按 MCP 接入，填同一组 command／args |

**核心能力：**

- 打开网址、后退、开关标签页；
- 读页面的“无障碍树”（按钮、链接、文字的结构化清单），模型不靠截图识别页面；
- 点击、输入、选下拉、填表单、上传文件、处理弹窗；
- 截图、下载文件，加参数后可存 PDF；
- 查看网络请求，在页面里执行一段 JavaScript。

**在同类工具里的位置：**它是浏览器自动化框架 Playwright（GitHub 98,055 星，2026-10 核查）的官方 MCP 版本。同一团队另出 CLI＋Skill 形态的 [Playwright CLI](https://ai.lingnan.top/materials/2026-autumn/w07/tool-04-playwright-cli)；和 [agent-browser](https://ai.lingnan.top/materials/2026-autumn/w07/tool-05-agent-browser)、[WorkBuddy 浏览器操控](https://ai.lingnan.top/materials/2026-autumn/w07/tool-02-workbuddy-browser) 相比，它是两端都能接的标准 MCP 写法，适合用来演示 MCP 接入。

**国内网络：**可用。从 npmmirror 能装上，装好后提供 25 个浏览器工具；浏览器内核下载可走 npmmirror，本机已有 Chrome／Edge 时不必下载。

## 1. 官方链接与版本

| 项目 | 链接 |
|:--|:--|
| GitHub 仓库（含 README，即官方文档） | https://github.com/microsoft/playwright-mcp （国内能打开，但慢且不稳定） |
| 更新日志（Releases） | https://github.com/microsoft/playwright-mcp/releases |
| npm 包 | https://www.npmjs.com/package/@playwright/mcp ；国内镜像 https://registry.npmmirror.com/@playwright/mcp |
| 浏览器扩展（接已开着的浏览器时用，本课不用） | https://github.com/microsoft/playwright/tree/main/packages/extension 。国内网络连不上 Chrome 应用店，Chrome 扩展装不上；Windows 上要用只能走 Edge 加载项商店，如果在那里搜不到这个扩展，就不用扩展这条路线 |
| 同门的 CLI＋Skills 方案 | https://github.com/microsoft/playwright-cli （npm 包 `@playwright/cli`，0.1.22），说明见 [Playwright CLI](https://ai.lingnan.top/materials/2026-autumn/w07/tool-04-playwright-cli) |
| 价格 | 免费开源，Apache-2.0；没有付费档 |

- 最新版本：**0.0.83**，2026-09-28 发布（npm `latest` 标签与 GitHub Releases 一致）。前几版：0.0.82（09-18）、0.0.81（09-14）、0.0.80（09-01），约两周一版。
- 仓库约 3.8 万星，默认分支最近推送 2026-10-16。
- 核查日期：2026-10-19。

**Node.js 版本要看一眼**：README 写“Node.js 18 or newer”，`@playwright/mcp` 包自己也声明 `node >=18`；但 0.0.83 依赖的 `playwright` 与 `playwright-core` 1.64 声明的是 `node >=20`。Node 18、20 都已停止维护，课程统一要求 **Node.js 22 或 24 LTS**。只按 README 检查“18 以上”会放过 Node 18 的机器。

## 2. 能做什么、不能做什么

**能做**（README 与工具列表）：

- 打开网址、后退、开关标签页（`browser_navigate`、`browser_navigate_back`、`browser_tabs`）
- 读页面：`browser_snapshot` 给出页面的“无障碍树”（按钮、链接、文字的结构化清单），模型不靠截图识别；`browser_find` 在页面里查文字，比读整页省 Token
- 操作：点击、输入、选下拉、填整张表单、按键、悬停、拖拽、上传文件、处理弹窗
- 截图、看控制台和网络请求；在页面里执行一段 JavaScript（`browser_evaluate`）
- 下载文件
- 加参数后开放的能力：`--caps=pdf` 存 PDF，`--caps=vision` 按坐标点击，`--caps=devtools` 录屏和录操作等

**做不了或不该让它做**：

- 扫码登录、验证码：要你在它开的窗口里自己处理
- 判断取回来的东西对不对、全不全：例如页面写 98 条，它可能只交第一页 30 条也不提漏了
- 小红书、知乎这类打开就要登录的站，登录后的批量采集有封号和违反站点条款的风险，本课不碰
- 不是安全边界（README 原话 “not a security boundary”），见第 6 节

**适合本课的任务**（巨潮、诺奖官网、IMF、搜狗微信、统计局在国内网络下都能打开）：巨潮资讯公告列表（要点按钮翻页）、诺奖官网或 IMF 报告页（直接请求 403、浏览器能打开）、搜狗微信搜索公众号文章、统计局或交易所页面上要点几层才出来的表格。纯文字的公开网页，先用 DeepSeek 的 Search 与 Fetch（见 [DeepSeek 搜索与读取](https://ai.lingnan.top/materials/2026-autumn/w07/tool-01-deepseek-web)），更快也更省 Token。Claude Code 自带的 WebFetch 在国内网络下不可用，不用它。

## 3. 安装与配置

### 3.0 前置条件

| 条件 | 怎样检查 | 说明 |
|:--|:--|:--|
| Node.js 22 或 24 LTS | 终端运行 `node --version` | 没有就装官网 LTS 安装包，或 `winget install OpenJS.NodeJS.LTS`；安装要点系统授权弹窗，自己点 |
| npm 源设为 npmmirror | `npm config get registry` | 显示 `https://registry.npmmirror.com/` 即可；不是就运行 `npm config set registry https://registry.npmmirror.com`。国内网络下 npmmirror 更快，官方源也能连上 |
| 浏览器：Chrome，或 Win11 自带的 Edge | 看下面的路径是否存在 | 它默认用本机 Chrome，**不另下载浏览器** |
| Claude Code 能正常对话，或 WorkBuddy 已登录 | — | — |

npm 是 Node.js 自带的软件包管理器，`npm install` 从“源”（软件包仓库）下载程序；npmmirror 是国内的镜像源。

Chrome 常见安装位置（任一存在即可）：

```txt
C:\Program Files\Google\Chrome\Application\chrome.exe
C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
C:\Users\<你的用户名>\AppData\Local\Google\Chrome\Application\chrome.exe
```

### 3.1 首选：交给智能体装（Claude Code）

在任意文件夹启动 Claude Code，把下面这段发给它：

```txt
帮我在这台 Windows 电脑上装 Playwright MCP（https://github.com/microsoft/playwright-mcp ，npm 包 @playwright/mcp），接到 Claude Code 的用户作用域。每一步做完把命令输出给我看。

1. 运行 node --version。没有 Node，或版本低于 22，停下告诉我，我自己去装 Node.js LTS。
2. 运行 npm config get registry。不是 https://registry.npmmirror.com/ 的话，运行 npm config set registry https://registry.npmmirror.com 。
3. 运行 npm install -g @playwright/mcp
   - 如果 PowerShell 报“禁止运行脚本”，改用 npm.cmd install -g @playwright/mcp，不要改执行策略。
   - 如果出现 install-scripts 相关的提示（npm 11.20 起默认不跑安装脚本），把提示原文给我看，不要自己运行 approve。
   - 报网络错误就停下告诉我，我用离线包。
4. 检查这几个位置有没有 chrome.exe：C:\Program Files\Google\Chrome\Application、C:\Program Files (x86)\Google\Chrome\Application、%LOCALAPPDATA%\Google\Chrome\Application。
   - 有 Chrome：运行 claude mcp add playwright -s user -- playwright-mcp
   - 没有 Chrome、只有 Edge：运行 claude mcp add playwright -s user -- playwright-mcp --browser msedge
   - 如果提示 playwright 已存在，先把现有配置给我看，我同意后再运行 claude mcp remove playwright -s user 重加。
5. 运行 claude mcp list，确认 playwright 显示已连接；再运行 npm ls -g @playwright/mcp 告诉我装的版本。

要避开的写法：不要用 npx，不要写 @latest，不要加 --browser chromium，不要运行 npx playwright install 或任何下载浏览器内核的命令，不要加 --extension 或 --cdp-endpoint（那样会接到我日常浏览器的登录状态）。
遇到要输密码、要管理员权限、要改系统设置、要下载额外安装包的情况，停下来问我。
做完提醒我退出 Claude Code 再重开，然后敲 /mcp 检查。
```

**它会请求哪些权限、怎么点**：

| 它要运行的命令 | 做什么 | 怎么点 |
|:--|:--|:--|
| `node --version`、`npm config get registry`、`npm ls -g ...`、检查 chrome.exe 路径 | 只读检查 | 允许 |
| `npm config set registry https://registry.npmmirror.com` | 把 npm 的下载源改成国内镜像，写进你用户目录下的 `.npmrc` | 看清地址是 `registry.npmmirror.com` 再允许 |
| `npm install -g @playwright/mcp`（或 `npm.cmd ...`） | 往你用户目录下的 npm 全局目录装 3 个包，约 19 MB | 看清包名是 `@playwright/mcp` 再允许 |
| `claude mcp add playwright -s user -- playwright-mcp ...` | 在你的 Claude Code 用户配置里登记这个服务器 | 看清末尾参数再允许 |
| `claude mcp remove playwright -s user` | 删掉已有的同名配置 | 先看它把原配置给你看过，再允许 |
| `Set-ExecutionPolicy`、`npx playwright install`、`--browser chromium`、`--extension` | 改系统脚本策略、下载浏览器内核、接日常浏览器 | 拒绝，让它换写法 |
| `npm install-scripts approve ...` | 放行某个包的安装脚本 | 本工具不需要，拒绝；先把提示原文看清 |

### 3.2 首选：交给智能体装（WorkBuddy）

WorkBuddy 也能在本机运行命令，可以让它完成检查和安装，最后把连接器配置交给你在界面里填。

```txt
帮我准备 Playwright MCP（npm 包 @playwright/mcp），之后我要在 WorkBuddy 的自定义连接器里接它。每一步把输出给我看：
1. 运行 node --version，低于 22 就停下告诉我。
2. 运行 npm config get registry，不是 https://registry.npmmirror.com/ 就运行 npm config set registry https://registry.npmmirror.com ；再运行 npm install -g @playwright/mcp（PowerShell 禁止脚本时改用 npm.cmd，不要改执行策略）。
3. 运行 npm root -g，拼出 @playwright\mcp\cli.js 的完整路径，确认这个文件存在。
4. 运行 where node，告诉我 node.exe 的完整路径。
5. 检查本机有没有 Chrome（C:\Program Files\Google\Chrome\Application 等位置）。
6. 按上面的结果，给我一段可以直接粘进 WorkBuddy 自定义连接器的 mcpServers JSON：command 用 node，args 第一项是 cli.js 的完整路径；没有 Chrome 时 args 里再加 "--browser" 和 "msedge"。路径里的反斜杠要写成两个。
不要改 WorkBuddy 的配置文件，不要用 npx 和 @latest，不要加 --browser chromium、--extension、--cdp-endpoint，不要下载浏览器内核。要管理员权限或要输密码时停下来问我。
```

它会请求的权限与 3.1 的表相同，照表处理。

### 3.3 要你亲手做的部分

1. **装 Node.js**：安装包会弹系统授权（UAC），要你点“是”。
2. **退出并重开客户端**：Claude Code 输入 `/exit` 再输入 `claude`（VS Code 插件开新会话）；WorkBuddy 保存连接器后看状态灯，必要时重启。
3. **WorkBuddy 填连接器**：见 3.5。
4. **网站要登录、出现验证码时**：在 Playwright 开的那个浏览器窗口里自己操作，不把账号密码发给智能体。
5. 这个工具不需要 API Key，没有 Key 要保管。

### 3.4 参考：手动安装命令（Claude Code）

Windows 11 x64，PowerShell 或 CMD：

```txt
npm config set registry https://registry.npmmirror.com
npm install -g @playwright/mcp
claude mcp add playwright -s user -- playwright-mcp
```

装好后得到 `@playwright/mcp` 0.0.83（连同依赖 `playwright-core` 1.64），启动后提供 25 个工具。

要点：

- **`-s user` 不能省。** 不加时默认作用域是 local，只在运行命令的那个文件夹生效，换到项目文件夹就看不到 playwright。
- **只有 Edge、没有 Chrome**：`claude mcp add playwright -s user -- playwright-mcp --browser msedge`。`--browser` 的官方可选值是 `chrome`、`firefox`、`webkit`、`msedge`。
- **不要写 `--browser chromium`**：会另下一份浏览器（压缩包一两百 MB），本机已有 Chrome 或 Edge 时没有必要。确实要下载时见下面“没有 Chrome 也没有 Edge”。`firefox`、`webkit` 同样要另下内核。
- **不用 `npx @playwright/mcp@latest`**：这是 README 的标准写法，但每次开会话都要联网检查版本，启动慢、网络一抖就卡住。全局安装后用 `playwright-mcp` 命令启动，版本固定在安装时那一版。
- PowerShell 提示 `npm.ps1` “禁止运行脚本”：改用 `npm.cmd install -g @playwright/mcp`，或换 CMD 窗口运行；不要为此关闭脚本执行保护。
- 没改源也可以只对这一次指定：`npm install -g @playwright/mcp --registry=https://registry.npmmirror.com`。
- npm 11.20 起默认不运行包的安装脚本（install-scripts 要批准），装包时可能出现 `npm warn install-scripts` 提示。`@playwright/mcp` 不受影响，装好后可以直接用，不需要批准什么。要查看时运行 `npm install-scripts ls`。
- **没有 Chrome 也没有 Edge**（少见）：从 npmmirror 下载 Chrome for Testing 的 Windows 包，地址形如 `https://cdn.npmmirror.com/binaries/chrome-for-testing/<版本号>/win64/chrome-win64.zip`，解压后在配置末尾加 `--executable-path "D:\tools\chrome-win64\chrome.exe"`。设了 `PLAYWRIGHT_DOWNLOAD_HOST`（或 `PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`）后，下载地址会变成 `<该值>/builds/cft/<版本号>/<平台文件>`，与 npmmirror 的目录结构对不上，不要把它指向 npmmirror；不设时默认从 cdn.playwright.dev 下载，国内网络能连上。
- 改参数（例如换成 Edge）前先删旧的：`claude mcp remove playwright -s user`，再重新 `add`。
- 开着 Clash 等代理、要打开 `localhost` 网页时，可给服务器加环境变量（PowerShell 写成一行）：

```txt
claude mcp add playwright -s user -e NO_PROXY=localhost,127.0.0.1 -e no_proxy=localhost,127.0.0.1 -- playwright-mcp
```

官方另有 `--proxy-server` 与 `--proxy-bypass` 两个参数，可直接给浏览器指定代理和排除名单。

**离线包（npm 走不通时）**：如果 npm 装不上，可以改用离线包：`playwright-mcp-0.0.83-离线包.zip`（约 4 MB，解压后约 19 MB，含 `@playwright/mcp`、`playwright`、`playwright-core` 三个包）。把 zip 里的 `node_modules` 整个解压到例如 `D:\playwright-mcp\`，然后：

```txt
claude mcp add playwright -s user -- node "D:\playwright-mcp\node_modules\@playwright\mcp\cli.js"
```

路径换成你自己的完整路径；只有 Edge 时末尾加 `--browser msedge`。离线包固定在 0.0.83，以后不会自动更新。

**macOS**：命令相同。`npm install -g` 报 `EACCES` 权限错误时，多半是 Node 用官网 pkg 装在系统目录，改用 Homebrew 或 nvm 装的 Node，不要加 `sudo`。

**升级**：`npm install -g @playwright/mcp@<版本号>`，再退出重开客户端。

### 3.5 参考：WorkBuddy 连接器里填同一组 command／args

入口（官方文档，两处都能配 MCP；界面按你安装的版本为准）：

- 左侧 **连接器** → 右上角 **自定义连接器**；官方说明“配置方式与 MCP 配置类似”
- 或 **插件** → 右上角 **MCP 服务器** → **配置 MCP**，粘贴 `mcpServers` JSON

配置级别：用户级 `~/.workbuddy/mcp.json`（所有项目可用）；项目级 `<项目目录>/.workbuddy/mcp.json`（只在该项目生效）。

**写法一：与 Claude Code 相同的命令**（先试这个）

```json
{
  "mcpServers": {
    "playwright": {
      "command": "playwright-mcp",
      "args": []
    }
  }
}
```

只有 Edge 时 `"args": ["--browser", "msedge"]`。

**写法二：node＋cli.js 完整路径**（写法一状态灯变红时用；离线包也用这个）

```json
{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": [
        "C:\\Users\\<你的用户名>\\AppData\\Roaming\\npm\\node_modules\\@playwright\\mcp\\cli.js"
      ]
    }
  }
}
```

- `cli.js` 的位置用 `npm root -g` 查，后面接 `\@playwright\mcp\cli.js`；离线包就写解压位置，例如 `D:\\playwright-mcp\\node_modules\\@playwright\\mcp\\cli.js`。
- JSON 里的反斜杠写两个；用户名会出现在路径里，截图前遮住。
- WorkBuddy 找不到 `node` 时，把 `command` 换成 `where node` 查到的完整路径，例如 `C:\\Program Files\\nodejs\\node.exe` 这一类（以你机器上查到的为准）。
- 为什么准备写法二：`playwright-mcp` 在 Windows 上实际是 `playwright-mcp.cmd` 包装文件，图形界面程序启动 `.cmd` 文件或读取 PATH 的方式与终端不一定相同；直接让 `node` 运行 `cli.js` 绕开了这一层。另一种写法是 `"command": "cmd", "args": ["/c", "playwright-mcp"]`。
- 填表单式界面时：类型选本地或 stdio；命令填 `node`（或 `playwright-mcp`）；参数逐项填，每个参数一行或一项，不要把整串写在一格里。字段名以界面为准。

保存后看状态：绿色为已连接，红色为配置异常（官方说明）。连接后新建任务再用。

WorkBuddy 内置连接器登记在 `~/.workbuddy/connectors/default/mcp.json`，格式同为 `mcpServers`。自定义连接器保存到哪个文件、改文件后是否自动生效，以界面为准；所以提示词里要求智能体不改 WorkBuddy 配置文件，由你在界面里填。

### 3.6 怎样确认装好了

1. `node --version` 显示 v22 或 v24。
2. `npm ls -g @playwright/mcp` 显示 `@playwright/mcp@0.0.83`（或你装的版本）。
3. Claude Code：`claude mcp list` 里 playwright 显示已连接；退出重开后敲 `/mcp`，列表里有 playwright。**再换一个文件夹启动 Claude Code 敲一次 `/mcp`**，还在才说明 `-s user` 生效了。
4. WorkBuddy：连接器或 MCP 服务器列表里 playwright 是绿灯。
5. 跑一句：

```txt
用浏览器打开 https://weixin.sogou.com/ ，告诉我页面标题是什么。
```

屏幕上弹出一个新的 Chrome（或 Edge）窗口，它报出标题，就通了。默认工具 25 个，名字都以 `browser_` 开头。搜狗微信在国内网络下能打开。

## 4. 使用教程：巨潮资讯取一家公司的公告列表

巨潮资讯（证监会指定的上市公司信息披露网站）的公告列表是页面打开后才生成的，网页源码里没有条目，翻页要点按钮。直接读网页拿不到，适合用浏览器做。

**准备**：新建一个空文件夹（例如 `D:\智能体练习\巨潮公告`），在里面启动 Claude Code，或在 WorkBuddy 里把它设为工作空间。

**提示词**：

```txt
用 Playwright 浏览器完成下面的任务，每一步告诉我你在做什么：
1. 打开 https://www.cninfo.com.cn/new/index ，搜索“贵州茅台”，进入它的公告列表。
2. 把公告类别筛选为“年报”或“定期报告”（页面上叫什么就点什么）。
3. 读取前两页的公告，每条记下：公告标题、公告日期、公告详情页链接。
4. 把结果存成当前文件夹下的 公告列表.csv（UTF-8 带 BOM，方便 Excel 打开），列名：标题,日期,链接,取得日期。取得日期填今天。
5. 告诉我：页面上显示一共有多少条、你实际取了几条、有没有因为没翻页而漏掉的。
规则：标题照页面原文抄，不改写；遇到验证码、要登录或页面打不开，马上停下告诉我；不下载 PDF。
```

**预期看到的工具调用**（顺序大致如此，实际以模型为准）：

| 步骤 | 工具 |
|:--|:--|
| 打开首页 | `browser_navigate` |
| 看页面上有什么 | `browser_snapshot` 或 `browser_find` |
| 输入公司名、点搜索、点筛选 | `browser_type`、`browser_click`、`browser_select_option` |
| 翻到第二页 | `browser_click`（点“下一页”或页码），再 `browser_snapshot` |
| 读整张表 | 可能用 `browser_evaluate` 在页面里执行一段脚本取出表格 |
| 存文件 | Claude Code 的写文件工具（不是 Playwright 的工具） |

**产出**：`公告列表.csv`；Playwright 自动命名的截图、快照等文件会放在工作目录下的 `.playwright-mcp\` 里（官方参数 `--output-dir` 可改）。

**怎样验收**：

1. 用 Excel 打开 CSV，中文不乱码，行数等于它报告的“实际取了几条”。
2. 回到巨潮页面，把第一页和第二页的条数自己数一遍，看有没有漏。
3. 随机挑 3 条，点链接能打开对应公告，标题、日期与表里一致。
4. 它报告的“页面显示总条数”与页面上写的一致；如果只取了前两页，它应当说明后面还有。

**换一个题目练**：搜狗微信搜索（https://weixin.sogou.com/ ）搜“2026 诺贝尔经济学奖”，取前 3 篇公众号文章存成 Markdown，记下标题、公众号、发布时间、链接、取得日期，正文照原文抄。很多人同时搜可能弹验证码，在浏览器窗口里自己过。

## 5. 常见问题与排错

| 现象 | 多半是 | 处理 |
|:--|:--|:--|
| `/mcp` 里没有 playwright | 注册时漏了 `-s user`，或没退出重开 | 换个文件夹再看一次确认；`claude mcp remove playwright -s user` 后加 `-s user` 重注册，退出重开 |
| PowerShell 报 `npm.ps1` 禁止运行脚本 | 系统脚本执行策略拦了 `npm.ps1` | 改用 `npm.cmd install -g @playwright/mcp`，或换 CMD；不改执行策略 |
| `npm install` 跑很久后失败 | 没改源，官方源慢或一时连不上 | `npm config set registry https://registry.npmmirror.com` 后重装；还不行用离线包 |
| 出现 `npm warn install-scripts` | npm 11.20 起默认不跑安装脚本 | 本工具不受影响，照常注册；不要随手 `approve` |
| 报 `Chromium distribution 'chrome' is not found` | 电脑上没装 Chrome | 末尾加 `--browser msedge`（先 remove 再 add） |
| 提示要下载 `chrome-for-testing` 或浏览器内核 | 用了 `--browser chromium`（或 firefox、webkit） | 去掉，用默认 Chrome 或 `--browser msedge`；两者都没有时按 3.4 从 npmmirror 手动下载 |
| 想装 Playwright 的 Chrome 扩展，应用店打不开 | 国内网络连不上 Chrome 应用店 | 本课不用扩展；确有需要在 Windows 上改用 Edge 加载项商店 |
| 每次开新会话都卡几秒到几十秒 | 配置里是 `npx @playwright/mcp@latest`，每次联网检查版本 | 改成全局安装＋`playwright-mcp` |
| 启动报 Node 版本或语法错误 | Node 低于 20（依赖包要求 `>=20`） | 升级到 Node 22 或 24 LTS |
| WorkBuddy 状态灯红 | 图形界面找不到 `playwright-mcp` 或 `node`，或 JSON 格式错 | 换 3.5 的写法二（node＋cli.js 完整路径，必要时 node.exe 也写完整路径）；检查反斜杠是否写两个、括号引号是否成对 |
| 报浏览器用户目录被占用、打不开 | 同一个工作文件夹里 Claude Code 和 WorkBuddy（或两个会话）同时用 Playwright，默认的持久用户目录同一时刻只能被一个浏览器使用（官方说明） | 关掉其中一个；要并行时给其中一个加 `--isolated` 或不同的 `--user-data-dir` |
| 页面内容不对、像登录页，或打不开 `localhost` | 代理把请求带偏了 | 加 `-e NO_PROXY=localhost,127.0.0.1`，或用 `--proxy-server`、`--proxy-bypass` |
| 页面弹验证码、要扫码 | 网站的反爬或登录要求 | 在它开的窗口里自己处理；频繁出现就降低频率或换数据来源 |
| 下载的文件找不到 | 不在桌面 | 看当时工作目录下的 `.playwright-mcp\` |
| 读公众号正文被改写成摘要 | 模型读了快照后自己概括了 | 提示词写“正文照原文抄”；或让它用 `browser_evaluate` 读正文节点（如 `#js_content`）的文字 |
| 它说取完了，条数却对不上 | 没翻页或没滚动加载 | 提示词要求报告“页面显示总数与实际取到数”，自己核对 |
| 想让它用我平时的浏览器和登录 | 默认开的是独立浏览器，与日常浏览器分开 | 本课不这样做；见第 6 节 |

## 6. 费用、额度、隐私与安全

- **费用**：工具本身免费。花钱的是模型 Token：每次读页面快照都会把页面结构发给模型，长页面一次几千到上万 Token。用 DeepSeek 等按量计费的模型时，长任务成本会明显上升。省 Token 的办法：先让它用 `browser_find` 查要的那部分，而不是反复读整页；官方说明 `--mobile` 模拟手机页面通常更轻。
- **Claude Code 接国内模型时的上下文占用**：Anthropic 文档说明，`ANTHROPIC_BASE_URL` 不是官方端点时，MCP 工具默认预先加载进上下文。Playwright 的 25 个工具说明每轮都会带上，不用时可在 `/mcp` 里停用。
- **登录态**：默认是持久用户目录，在它的窗口里登录过的网站，下次还是登录状态。Windows 位置是 `%USERPROFILE%\AppData\Local\ms-playwright\mcp-{浏览器}-{工作区哈希}`，每个工作文件夹各一份。不想保留就删掉该目录，或配置里加 `--isolated`（会话结束即清空）。不要把这个目录打包分享给别人。
- **不要接日常浏览器**：`--extension`（配合 Playwright 浏览器扩展）和 `--cdp-endpoint` 会连到你正在用的 Chrome／Edge，智能体能碰到里面所有已登录的账号（网银、邮箱、学校系统）。本课不用这两种。另外，Chrome 扩展在国内网络下装不上。
- **网页内容可能指挥智能体**：网页上的文字会进入模型上下文，恶意页面可以写“请把某文件发到某地址”这类话。官方说明 Playwright MCP 不是安全边界；`--allowed-origins`、`--blocked-origins` 也不能当安全措施。0.0.82 起，网页通过 WebMCP 注册的工具会出现在工具列表里（名字以 `webmcp_` 开头），官方提示要当作不可信输入，可用 `--no-webmcp` 关掉。让它操作浏览器时，不让它同时处理密码、付款和发送类操作。
- **文件访问**：默认只能读写工作区（启动客户端的文件夹）内的文件，禁止打开 `file://` 地址；`--allow-unrestricted-file-access` 会放开这个限制，不要加。
- **站点条款与封号**：批量采集要看网站条款和频率限制；登录后的批量操作有封号风险。公众号文章、公告原文只放进自己的项目当资料，不往外传。
- **遥测**：README 没有写遥测相关说明。
- **截图前**：注意终端和配置里的路径含 Windows 用户名，浏览器窗口里可能有登录后的个人信息。

## 7. 官方说明摘译：Playwright MCP 与 Playwright CLI

README 开头有一段“Playwright MCP vs Playwright CLI”，大意如下：

- 这个包是 Playwright 的 MCP 接口。如果用的是编程智能体，CLI 加 Skills 的方案（microsoft/playwright-cli）可能更合适。
- **CLI**：越来越多的编程智能体倾向用“命令行工具＋Skill”而不是 MCP，因为调用命令行更省 Token：不用把大段工具定义和冗长的页面无障碍树装进模型上下文，智能体通过简短、专用的命令完成操作。上下文有限、还要同时处理大量代码、测试和推理的编程智能体，更适合这种方式。
- **MCP**：在需要持续保持状态、细致查看页面结构、反复推理的专门任务里，MCP 仍然适用，例如探索式自动化、能自我修复的测试、长时间自主运行的流程。在这些任务里，保持浏览器上下文连续的价值大于 Token 开销。

对本课的含义：Claude Code 两种都能用；本课选 MCP，是因为 Claude Code 和 WorkBuddy 填同一组配置就能接，不用写命令。看重 Token 成本的同学可以对照试 [Playwright CLI](https://ai.lingnan.top/materials/2026-autumn/w07/tool-04-playwright-cli)。

## 8. 与同类工具的一句对比

Playwright MCP 开一个独立浏览器、两端都按 MCP 接；[agent-browser](https://ai.lingnan.top/materials/2026-autumn/w07/tool-05-agent-browser) 与 [Playwright CLI](https://ai.lingnan.top/materials/2026-autumn/w07/tool-04-playwright-cli) 是“命令行＋Skill”路线，更省 Token、要装 CLI；[web-access](https://ai.lingnan.top/materials/2026-autumn/w07/tool-07-web-access) 一类接的是日常浏览器，能用登录态，也因此风险更高（Claude in Chrome 依赖 Anthropic 账号与 Chrome 扩展，国内网络不推荐）；[DeepSeek Search／Fetch](https://ai.lingnan.top/materials/2026-autumn/w07/tool-01-deepseek-web) 不开浏览器，适合公开静态页的搜索和正文提取。

## 9. 参考链接

| 内容 | 来源 |
|:--|:--|
| 版本 0.0.83 与发布日期、各版更新内容、WebMCP 不可信提示 | https://github.com/microsoft/playwright-mcp/releases |
| 参数表（`--browser` 可选值、`--isolated`、`--output-dir`、代理参数等）、持久用户目录位置与并发限制、“not a security boundary”、MCP vs CLI 段落、Claude Code 标准命令 | https://github.com/microsoft/playwright-mcp#readme |
| npm 包页面（版本、依赖） | https://www.npmjs.com/package/@playwright/mcp |
| Playwright CLI | https://github.com/microsoft/playwright-cli ；https://www.npmjs.com/package/@playwright/cli |
| WorkBuddy 连接器、自定义连接器入口 | https://www.workbuddy.ai/docs/zh/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Connector |
| WorkBuddy MCP 配置入口、用户级与项目级 `mcp.json`、状态灯含义 | https://www.workbuddy.ai/docs/zh/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/MCP-Guide |
| 非官方端点下 MCP 工具预加载 | https://code.claude.com/docs/en/mcp |