Claude Code教程（九）| MCP 之 Playwright
Claude Code教程（九）| MCP 之 Playwright
- 一、是什么
- 二、前置条件
- 三、接入方式
- 方式一：claude mcp add（推荐）
- 方式二：手动 JSON 配置
- 方式三：Docker 模式
- 四、Windows 注意事项
- 五、验证
- 六、使用方式
- 七、常用配置参数
- 八、核心工具一览
- 九、浏览器持久化
一、是什么
Playwright MCP 是 Microsoft 官方提供的 MCP Server，基于 Playwright 实现浏览器自动化。它通过浏览器的accessibility tree（无障碍树）获取页面结构化数据，而非依赖像素截图，因此速度快、结果确定性强、不消耗 vision 模型。
接入后 Agent 可直接控制浏览器：打开页面、点击、填表、截图、执行 JS、网络拦截等。
二、前置条件
- Node.js >= 18
- 首次运行时 Playwright 会自动下载浏览器二进制（Chromium / Firefox / WebKit）
三、接入方式
方式一：claude mcp add（推荐）
场景一：全局，所有项目生效（推荐）
配置文件~/.claude.json→ 根节点
claude mcpadd-suser playwright npx'@playwright/mcp@latest'卸载：
claude mcp remove-suser playwright场景二：当前项目，可团队共享
配置文件 项目根.mcp.json
claude mcpadd-sproject playwright npx'@playwright/mcp@latest'卸载：
claude mcp remove-sproject playwright场景三：仅当前目录
配置文件~/.claude.json→ 该目录节点
claude mcpaddplaywright npx'@playwright/mcp@latest'卸载：
claude mcp remove playwright方式二：手动 JSON 配置
全局 → 编辑~/.claude.json：
{"mcpServers":{"playwright":{"command":"npx","args":["@playwright/mcp@latest"]}}}项目级 → 编辑项目根目录.mcp.json，内容同上，可提交 Git 供团队共享。
卸载：删除配置文件中对应的playwright条目，或直接删除.mcp.json文件。
方式三：Docker 模式
dockerrun-p8931:8931 mcr.microsoft.com/playwright/mcp仅支持 headless Chromium，功能受限，一般不推荐。
卸载：
dockerstop<容器ID>dockerrm<容器ID>四、Windows 注意事项
Playwright MCP 只有本地 npx 模式，没有远程 HTTP 服务端。如果出现MCP error -32000: Connection closed，改为cmd /c包裹：
{"mcpServers":{"playwright":{"command":"cmd","args":["/c","npx","@playwright/mcp@latest"]}}}五、验证
claude mcp list看到playwright且状态为 ✓ Connected 即成功。
六、使用方式
重启 Claude Code 会话后（新 MCP server 不会在当前会话加载），直接描述浏览器操作：
“用 playwright mcp 打开 example.com，截个图”
“playwright 打开百度首页，搜索 Claude Code”
Agent 会依次调用browser_navigate→browser_snapshot→browser_click等工具自动完成。
七、常用配置参数
claude mcpadd-suser playwright npx'@playwright/mcp@latest'--headless--isolated| 参数 | 作用 | 默认值 |
|---|---|---|
--headless | 无头模式，不显示窗口 | 关闭（headed） |
--browser | 浏览器类型：chromefirefoxwebkitmsedge | 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 <路径>