Playwright MCP Claude Code 配置教程：一步步上手

一行命令安装

要在 Claude Code 中使用 Playwright MCP，运行 claude mcp add playwright npx @playwright/mcp@latest，启动 claude，然后在 /mcp 中确认 playwright 显示为已连接。从此以后，Claude 就能通过微软官方的 Playwright MCP 服务器打开真实浏览器，点击、输入、读取页面并截图。

这条命令直接来自 Playwright MCP README。本文剩下的部分讲的是跑通之后马上会遇到的选择：装在哪个作用域、有头还是无头、持久化还是隔离的浏览器配置文件、额外能力，以及浏览器启动不了时怎么办。

Playwright MCP 到底做了什么

Playwright MCP 把浏览器自动化封装成 MCP 工具，比如 browser_navigate、browser_click、browser_type、browser_fill_form、browser_snapshot 和 browser_take_screenshot。它不把截图发给模型，而是返回无障碍快照（accessibility snapshot）：一棵结构化的页面元素树，带有 Claude 可以点击或填写的引用。因此它速度快，比基于视觉的方案更省，而且对操作哪个元素是确定的。

在 Claude Code 中的典型用法：

• 检查刚写好的功能在浏览器里是否真的能用。
• 按工单描述一步步复现 UI 缺陷。
• 先探索网站，再为它编写 Playwright 测试。
• 填写表单，或从依赖 JavaScript 的页面中提取数据。

前置条件

• Node.js 18 或更高版本（README 中写明的要求）。用 node --version 检查。
• 已安装并登录 Claude Code。
• 一个 Playwright 能驱动的浏览器。可以用 --browser 选择 chrome、firefox、webkit 或 msedge。

第 1 步：添加服务器

最快：local 作用域

claude mcp add playwright npx @playwright/mcp@latest

这会把服务器保存到默认的 local 作用域，只对你在当前项目中可用。

所有项目可用：user 作用域

claude mcp add --scope user playwright -- npx @playwright/mcp@latest

给 Playwright MCP 本身传参数时，一定要把启动命令放在 -- 之后，这样 Claude Code 就不会把 --headless 之类的参数当成自己的选项。

与团队共享：project 作用域

claude mcp add --scope project playwright -- npx @playwright/mcp@latest

这会在项目根目录写入一个可以提交的 .mcp.json：

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

队友第一次在仓库中运行 claude 时会被要求批准该服务器。作用域和批准机制的整体说明，见我们的 Claude Code MCP 指南。

第 2 步：验证连接

claude mcp list

你应该看到 playwright 显示 ✔ Connected。在会话中，/mcp 会显示同样的状态以及工具列表。如果显示 ✘ Failed to connect，直接跳到下面的故障排查表。

第 3 步：运行第一个提示词

第一次使用时要明确点名工具，否则 Claude 可能会改用 shell 写一个 Playwright 脚本去跑：

Use the playwright MCP to open https://mcp.so, search for "github",
and tell me the first three results.

浏览器窗口会弹出来（服务器默认是有头模式），你可以看着 Claude 操作页面。除非你已允许，Claude Code 在使用每个新工具前都会请求权限。

常用参数

所有参数都写在启动命令的包名之后，或写进 .mcp.json 的 args 数组。每个参数也都有对应的 PLAYWRIGHT_MCP_* 环境变量。

无头、隔离的 Firefox 配置如下：

claude mcp add playwright -- npx @playwright/mcp@latest \
  --headless --browser firefox --isolated

在 .mcp.json 中写法相同，这里还启用了 PDF 和 vision 工具：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--isolated",
        "--caps=vision,pdf"
      ]
    }
  }
}

能力详解

• vision 增加基于坐标的鼠标工具，适合 canvas 应用，或在无障碍树中显示不佳的元素。
• pdf 增加 browser_pdf_save。
• devtools 增加追踪、录屏和元素高亮。

README 还列出了网络模拟、Cookie 与存储、配置以及测试断言等可选工具组。只启用你需要的：每多一个工具，Claude 就要多考虑一份定义。

配置文件与登录

Playwright MCP 默认使用持久化配置文件，所以登录状态会跨会话保留。配置文件按项目分别存储：

• macOS：~/Library/Caches/ms-playwright/mcp- 后接浏览器渠道和工作区哈希
• Linux：~/.cache/ms-playwright/mcp- 后接浏览器渠道和工作区哈希
• Windows：%USERPROFILE%\AppData\Local\ms-playwright\mcp- 后接浏览器渠道和工作区哈希

删除该文件夹即可退出所有登录。一个持久化配置文件同一时间只能被一个浏览器使用，所以如果你在同一个项目的两个终端里运行 Claude Code，第二个要加 --isolated 或使用不同的 --user-data-dir。

如果任务需要用你真实的账号，--extension 模式会连接你自己 Chrome 或 Edge 中的标签页，而不是另开浏览器。请慎重使用：Claude 在浏览器里能做的任何事，都是以你的身份做的。在让 Agent 操作已登录的生产账号之前，先读一读 MCP 安全最佳实践。

好用的示例提示词

• 「Use playwright mcp to open http://localhost:3000，用测试邮箱注册，告诉我欢迎页是否能正常加载且没有控制台错误。」
• 「打开定价页，分别以 1280x720 和 iPhone 视口截图，列出布局差异。」
• 「在浏览器中按这份缺陷报告一步步复现，停在第一个失败的步骤。」
• 「先探索结账流程，再在 tests/checkout.spec.ts 中写一个覆盖正常路径的 Playwright 测试。」
• 「用示例数据填写联系表单并提交，报告网络响应。」

故障排查

想确切看到服务器暴露了哪些工具、返回了什么，可以把它连到 MCP Inspector。

改用 Docker 运行

README 还提供了容器镜像，目前只支持无头 Chromium：

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "--pull=always",
        "mcr.microsoft.com/playwright/mcp"
      ]
    }
  }
}

如果你已经通过网关统一管理服务器，参见 Docker MCP Gateway 配置。

Playwright MCP 与 Playwright CLI

Playwright 团队坦言，编码 Agent 有时用 Playwright CLI 加 skills 效果更好，因为简短的 CLI 调用避免了把大量工具定义和无障碍树塞进上下文。当 Claude 需要保持浏览器打开、一步步推理页面结构时，比如探索式测试或自愈测试，MCP 仍然更合适。在 Claude Code 中，工具搜索本来就会把用不到的工具定义挡在上下文之外，所以交互式浏览器任务默认用 MCP 没问题；长时间、高频率的批量运行可以考虑 CLI。

如果你只需要一个更简单的无头抓取工具，Puppeteer MCP 服务器也是一个选择，但 Playwright MCP 是微软官方的跨浏览器方案。

下一步

Playwright MCP 跑通后，可以搭配能形成闭环的服务器：用问题跟踪工具读取缺陷报告，或用 GitHub MCP 服务器提交带修复和新测试的 PR。更多服务器可以浏览 MCP 服务器目录，或阅读完整的 Claude Code MCP 指南来管理你添加的一切。