Claude Code教程（九）| MCP 之 Playwright

一、是什么
二、前置条件
三、接入方式
- [方式一：claude mcp add（推荐）](#方式一：claude mcp add（推荐）)
- [方式二：手动 JSON 配置](#方式二：手动 JSON 配置)
- [方式三：Docker 模式](#方式三：Docker 模式)
[四、Windows 注意事项](#四、Windows 注意事项)
五、验证
六、使用方式
七、常用配置参数
八、核心工具一览
九、浏览器持久化

一、是什么

Playwright MCP 是 Microsoft 官方提供的 MCP Server，基于 Playwright 实现浏览器自动化。它通过浏览器的 accessibility tree（无障碍树） 获取页面结构化数据，而非依赖像素截图，因此速度快、结果确定性强、不消耗 vision 模型。

接入后 Agent 可直接控制浏览器：打开页面、点击、填表、截图、执行 JS、网络拦截等。

二、前置条件

Node.js >= 18
首次运行时 Playwright 会自动下载浏览器二进制（Chromium / Firefox / WebKit）

三、接入方式

方式一：claude mcp add（推荐）

场景一：全局，所有项目生效（推荐）

配置文件 ~/.claude.json → 根节点

bash 复制代码

claude mcp add -s user playwright npx '@playwright/mcp@latest'

卸载：

bash 复制代码

claude mcp remove -s user playwright

场景二：当前项目，可团队共享

配置文件项目根 .mcp.json

bash 复制代码

claude mcp add -s project playwright npx '@playwright/mcp@latest'

卸载：

bash 复制代码

claude mcp remove -s project playwright

场景三：仅当前目录

配置文件 ~/.claude.json → 该目录节点

bash 复制代码

claude mcp add playwright npx '@playwright/mcp@latest'

卸载：

bash 复制代码

claude mcp remove playwright

方式二：手动 JSON 配置

全局 → 编辑 ~/.claude.json：

json 复制代码

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

项目级 → 编辑项目根目录 .mcp.json，内容同上，可提交 Git 供团队共享。

卸载：删除配置文件中对应的 playwright 条目，或直接删除 .mcp.json 文件。

方式三：Docker 模式

bash 复制代码

docker run -p 8931:8931 mcr.microsoft.com/playwright/mcp

仅支持 headless Chromium，功能受限，一般不推荐。

卸载：

bash 复制代码

docker stop <容器ID>
docker rm <容器ID>

四、Windows 注意事项

Playwright MCP 只有本地 npx 模式，没有远程 HTTP 服务端。如果出现 MCP error -32000: Connection closed，改为 cmd /c 包裹：

json 复制代码

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

五、验证

bash 复制代码

claude mcp list

看到 playwright 且状态为 ✓ Connected 即成功。

六、使用方式

重启 Claude Code 会话后（新 MCP server 不会在当前会话加载），直接描述浏览器操作：

"用 playwright mcp 打开 example.com，截个图"

"playwright 打开百度首页，搜索 Claude Code"

Agent 会依次调用 browser_navigate → browser_snapshot → browser_click 等工具自动完成。

七、常用配置参数

bash 复制代码

claude mcp add -s user playwright npx '@playwright/mcp@latest' --headless --isolated

参数	作用	默认值
`--headless`	无头模式，不显示窗口	关闭（headed）
`--browser`	浏览器类型：`chrome` `firefox` `webkit` `msedge`	chrome
`--isolated`	每次启动干净浏览器，不保存登录态	关闭
`--caps vision`	启用像素级鼠标操作（坐标点击、拖拽）	关闭
`--caps pdf`	启用 PDF 生成	关闭
`--caps devtools`	启用 trace、录像、元素高亮	关闭
`--timeout-action`	操作超时，单位毫秒	5000
`--timeout-navigation`	导航超时，单位毫秒	60000

添加后如需修改，先 claude mcp remove -s user playwright 卸载，再 claude mcp add 重新添加新参数。

八、核心工具一览

工具	用途
`browser_navigate`	打开指定 URL
`browser_snapshot`	获取页面无障碍树结构
`browser_click`	点击元素
`browser_type`	输入文本
`browser_take_screenshot`	截屏
`browser_evaluate`	执行 JavaScript
`browser_fill_form`	批量填表
`browser_network_requests`	查看网络请求
`browser_console_messages`	查看控制台日志
`browser_close`	关闭浏览器

更多工具（鼠标像素操作、PDF 生成、录屏等）通过 --caps 参数启用。

九、浏览器持久化

默认浏览器登录态保存到 ~/.cache/ms-playwright/mcp-{channel}-{hash}，关浏览器再开会话丢失。

需要每次干净环境 → 加 --isolated
需要指定保存位置 → 加 --user-data-dir <路径>