工具说明：Playwright MCP

项目介绍

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

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

核心能力：

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

**在同类工具里的位置：**它是浏览器自动化框架 Playwright（GitHub 98,055 星，2026-10 核查）的官方 MCP 版本。同一团队另出 CLI＋Skill 形态的 Playwright CLI；和 agent-browser、WorkBuddy 浏览器操控 相比，它是两端都能接的标准 MCP 写法，适合用来演示 MCP 接入。

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

1. 官方链接与版本

• 最新版本：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 搜索与读取），更快也更省 Token。Claude Code 自带的 WebFetch 在国内网络下不可用，不用它。

3. 安装与配置

3.0 前置条件

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

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

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，把下面这段发给它：

帮我在这台 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 检查。

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

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

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

帮我准备 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：

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 写成一行）：

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\，然后：

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 相同的命令（先试这个）

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

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

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

{
  "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. 跑一句：

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

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

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

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

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

提示词：

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

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

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

怎样验收：

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

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

5. 常见问题与排错

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。

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

Playwright MCP 开一个独立浏览器、两端都按 MCP 接；agent-browser 与 Playwright CLI 是“命令行＋Skill”路线，更省 Token、要装 CLI；web-access 一类接的是日常浏览器，能用登录态，也因此风险更高（Claude in Chrome 依赖 Anthropic 账号与 Chrome 扩展，国内网络不推荐）；DeepSeek Search／Fetch 不开浏览器，适合公开静态页的搜索和正文提取。

9. 参考链接