Playwright MCP 实战：让 Claude、Codex、Cursor 直接控制浏览器

你在 .codex/config.toml 里加了一行 [mcp_servers.playwright]，运行 codex 后浏览器确实打开了，但 AI 就是不调用浏览器工具——或者打开了页面，却找不到导航栏里的按钮。这篇文章给出 Claude Code、Codex、Cursor 三种客户端的完整配置步骤，第一次验证任务的验收清单，以及哪些浏览器权限不能随便交给 AI。

---

Playwright MCP 是什么

Playwright MCP 是 Microsoft 官方维护的 MCP server，把 Playwright 的浏览器自动化能力通过 Model Context Protocol 暴露给 AI 编程工具。它的核心原理不是截图识别，而是操作 accessibility tree——给 AI 一个网页的结构化视图，让它能找到按钮、链接、输入框等可交互元素。

核心能力与工具列表

Playwright MCP 提供的工具覆盖了浏览器自动化的主要场景：

• 导航：打开 URL、前进后退、刷新
• 点击与输入：点击元素、填写表单、键盘操作
• 截图与快照：截取页面截图、获取 accessibility snapshot
• 对话框与标签页：处理 alert/confirm/prompt、管理多标签页
• 网络与控制台：拦截网络请求、捕获 console log
• 存储状态：保存和恢复 cookies、localStorage、sessionStorage

这些能力让它能处理从简单页面点击到复杂表单提交的自动化任务。

与 Playwright CLI/SKILLS 的区别

Microsoft 官方 README 明确指出两种路线的取舍：

• MCP 路线：适合需要持久状态、丰富 introspection、持续浏览器上下文的场景，例如探索式自动化、自修复测试或长任务。缺点是工具 schema 和 accessibility tree 会带入上下文，占用 token。
• CLI + SKILLS 路线：适合高吞吐代码工作流，上下文占用更小，但需要你用命令行或脚本调用 Playwright。

如果你已经在用 Claude Code、Codex、Cursor 等支持 MCP 的 AI 编程工具，Playwright MCP 是把浏览器工具接入现有工作流的最直接方式。

与 Browser Use 的区别

Browser Use 是一个 Python agent loop，你需要写 Python 代码调用它的 API，然后 agent 会根据 prompt 决定浏览器操作。Playwright MCP 不同——它不提供 agent loop，只提供浏览器工具层，让你现有的 MCP client（Claude Code、Codex、Cursor）自己决定什么时候调用浏览器工具。

如果你是 Python 开发者想快速上手 Browser Agent，可以先看 Browser Use 入门教程：用 AI 自动打开网页、点击按钮和提取信息。如果你已经在用 MCP client，想把浏览器能力接入现有工具，这篇文章帮你把 Playwright MCP 装好、跑通、配置安全。

不是测试框架的替代品

Playwright MCP 不是 Playwright 测试框架的替代品。它适合探索式自动化和前端验收，但稳定的 E2E 测试套件仍然需要用 Playwright 测试框架 写测试脚本——因为测试需要确定性、可重复、可维护，AI 的浏览器操作不可控。如果你对浏览器模式下的测试感兴趣，可以看 Vitest Browser Mode。

---

Claude Code 配置 Playwright MCP

前置条件

Claude Code 需要 Node.js 18+ 才能运行 Playwright MCP。检查你的 Node 版本：

node --version

如果低于 18，需要先升级 Node.js。

添加命令

Claude Code 提供了专门的 MCP 管理命令。在项目根目录执行：

claude mcp add playwright npx @playwright/mcp@latest

这个命令会把 Playwright MCP server 注册到 Claude Code。注意使用 @playwright/mcp@latest，不要照搬旧社区包名（如 @executeautomation/playwright-mcp-server）。

项目级配置 .mcp.json

如果你想把 Playwright MCP 配置共享给团队成员，可以在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "BROWSER_PATH": "/usr/bin/chromium"
      }
    }
  }
}

Claude Code 发现项目级 .mcp.json 时会提示审批，出于安全考虑防止项目引入未信任的 MCP server。

环境变量展开

.mcp.json 支持环境变量展开，用于机器路径和敏感值：

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

Tool Search 和输出 token 管理

Claude Code 默认启用 MCP Tool Search，会延迟加载工具，降低上下文占用。MCP 输出大时 Claude Code 会进行 token 管理，默认最大输出 25,000 tokens。如果你发现 AI 没有使用浏览器工具，检查：

1. MCP server 是否正确启动（查看 Claude Code 日志）
2. Tool Search 是否启用（Claude Code 默认启用）
3. Node.js 版本是否 >= 18

---

Codex 配置 Playwright MCP

OpenAI Codex 在 CLI 和 IDE extension 中都支持 MCP servers，配置方式与 Claude Code 不同。

添加命令

Codex CLI 提供了 MCP 管理命令：

codex mcp add playwright -- npx @playwright/mcp@latest

注意 Codex 命令需要用 -- 分隔 server 名称和实际命令。

配置文件位置

Codex MCP 配置存储在 config.toml，有两种位置：

• 用户级：~/.codex/config.toml（全局生效）
• 项目级：项目根目录 .codex/config.toml（仅该项目生效）

CLI 和 IDE extension 共享配置。

config.toml 配置片段

手动配置时，在 config.toml 中添加：

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

如果需要传递环境变量或调整工具审批，再加上：

env_vars = ["HOME", "STORAGE_STATE_PATH"]
approval_mode = "prompt"

工具审批模式

Codex 提供三种工具审批模式：

• approval_mode = "allow"：自动执行所有工具调用
• approval_mode = "prompt"：每次工具调用前请求用户确认
• approval_mode = "deny"：拒绝所有工具调用

对于 Playwright MCP 的高风险工具（如 browser_run_code_unsafe），建议设置：

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
disabled_tools = ["browser_run_code_unsafe"]
approval_mode = "prompt"

这样能防止高风险工具自动执行，敏感操作需要人工审批。

HTTP server 支持

Codex 支持两种 MCP server 类型：

• STDIO server：本地进程通信，适合需要本机系统访问的工具（如 Playwright MCP）
• HTTP server：支持 bearer token 和 OAuth 认证

Playwright MCP 使用 STDIO，不需要配置 HTTP。

---

Cursor 配置 Playwright MCP

Cursor 的 MCP 配置通过 Settings UI 完成，与 Claude Code 和 Codex 的命令行方式不同。

UI 配置步骤

根据 Playwright 官方文档，Cursor 配置步骤如下：

1. 打开 Cursor Settings（Cmd+, 或菜单栏 Settings）
2. 导航到 MCP 设置页（Settings -> MCP）
3. 点击 “Add new MCP Server”
4. 填写配置：
   • Server name：playwright
   • Command type：npx
   • Command：@playwright/mcp@latest

标准参数配置

Cursor 的 MCP server 配置支持 Playwright MCP 的标准参数：

• --headless：无头模式（开发阶段建议 headed）
• --browser：选择浏览器（chrome/firefox/webkit/msedge）
• --output-dir：输出目录路径
• --storage-state：登录态文件路径

完整的参数说明见下文”标准配置参数对照表”。

配置参考

Cursor 官方 MCP 文档可以通过 Cursor 官方文档 查看。配置细节以 Playwright 官方文档和 Microsoft README 为准，确保使用官方包名 @playwright/mcp@latest。

---

标准配置参数对照表

Playwright MCP 提供多个配置参数，控制浏览器行为、安全边界和输出管理。

参数	作用	默认值	安全提示
--headless	无头模式，不显示浏览器窗口	false（headed）	开发阶段建议 headed 方便观察浏览器操作
--browser	选择浏览器类型	chrome	可选：chrome、firefox、webkit、msedge
--allowed-origins	允许访问的域名列表	无限制	不是安全边界，不影响 redirects，不能用它防止访问敏感网站
--blocked-origins	禁止访问的域名列表	无	不是安全边界，同上
--isolated	隔离模式，每次会话使用独立 profile	false	推荐用于并发 client 或多项目
--storage-state	指定登录态文件路径	无	保存 cookies 和 localStorage，谨慎使用真实账号
--output-dir	输出目录（截图、日志等）	无	指定路径方便查找结果
--save-session	保存会话状态	false	配合 persistent profile 使用
--snapshot-mode	accessibility snapshot 模式	default	控制快照详细程度
--allow-unrestricted-file-access	允许无限制文件访问	false	高风险，谨慎启用
--secrets	密钥配置（环境变量或文件）	无	用于敏感信息管理

关键提醒：官方明确说明 --allowed-origins 和 --blocked-origins 不是安全边界，且不影响 redirects。如果你需要限制 AI 访问的网站，不能依赖这两个参数。

---

Profile 模式三路线对照表

Playwright MCP 支持三种 profile 模式，影响登录态保存、并发支持和安全边界。

模式	登录态保存	Profile 路径	并发支持	适用场景	安全建议
persistent	保存 cookies、localStorage 等	macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}	一个 profile 同时只能一个 browser instance	需要 AI 记住登录状态的长任务	不建议用真实账号，从测试账号开始
isolated	不保存，每次会话独立	临时目录，每次会话自动清理	支持并发 client 或多项目	测试、探索、不需要登录态的场景	推荐生产环境首选
browser extension	保存（取决于浏览器）	浏览器扩展目录	取决于浏览器	连接已有浏览器会话	高级用法，需理解浏览器扩展安全模型

persistent profile 的限制

一个 persistent profile 同时只能由一个 browser instance 使用。如果你需要并发 client 或多项目同时使用 Playwright MCP，需要：

• 使用 --isolated 模式
• 或为不同 client 配置不同的 --user-data-dir

macOS 上的 persistent profile 路径示例：

~/Library/Caches/ms-playwright/mcp-chrome-a1b2c3d4

路径中的 {workspace-hash} 会根据项目自动生成，不同项目使用不同 profile。

登录态与安全边界

persistent profile 会保存 cookies、localStorage、sessionStorage，AI 可以访问你保存在浏览器中的登录态。如果你用真实账号登录，AI 可能能访问你的个人数据、支付信息、账号设置。

推荐做法：

• 生产环境使用 --isolated，不保存登录态
• 需要 AI 操作登录态时，使用测试账号，不要用真实账号
• 不要让 AI 自动登录你的真实账号或访问支付页面

登录态管理的深入讨论留给后续文章（AI 浏览器登录态管理），本篇只做边界提醒。

---

browser_run_code_unsafe 安全警告

安全警告：browser_run_code_unsafe 允许执行任意 Playwright 脚本，官方标注为 RCE-equivalent（远程代码执行等效）。只能在完全信任的 MCP clients 上启用，生产环境建议禁用或通过 Codex 的 approval_mode: prompt 进行人工审批。

Playwright MCP 提供了一个高风险工具 browser_run_code_unsafe，它可以在浏览器上下文中执行任意 Playwright 脚本。这个能力的危险性在于：

• 如果 MCP client 被攻破或 AI 行为不可控，攻击者可以通过这个工具执行任意代码
• AI 可以读取浏览器中的所有数据，包括 cookies、localStorage、sessionStorage、已登录账号的个人信息
• 如果浏览器正在访问支付页面、账号设置等敏感页面，AI 可以读取并外泄数据

安全配置建议

生产环境：

1. 禁用 browser_run_code_unsafe：

   在 Codex 的 ~/.codex/config.toml 中添加：

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   disabled_tools = ["browser_run_code_unsafe"]

2. 或设置审批模式：

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   approval_mode = "prompt"

   这样每次调用 browser_run_code_unsafe 前，Codex 会弹出确认对话框，需要你手动批准。

开发环境：

如果你确实需要使用 browser_run_code_unsafe：

• 只在本地开发环境启用，不要在生产环境或真实账号上使用
• 确保你完全理解要执行的脚本内容
• 不要让 AI 自动生成并执行脚本，而是你自己写好脚本，让 AI 执行

不建议新手使用

如果你刚接触 Playwright MCP，不建议使用 browser_run_code_unsafe。优先使用 Playwright MCP 提供的其他安全工具（如 browser_click、browser_navigate、browser_screenshot），这些工具有明确的边界，不会执行任意代码。

---

MCP Tools 安全建议清单

MCP 协议让 AI 能调用外部工具，但”接上 MCP”不等于”让 AI 自动做任何事”。你需要从客户端侧和服务端侧两方面控制安全边界。

客户端侧安全建议

1. 敏感操作请求用户确认：在调用 browser_run_code_unsafe、访问支付页面、修改账号设置、删除数据前，提示用户确认。不要让 AI 自动执行这些高风险操作。

2. 调用前展示 tool inputs：让用户看到 AI 即将执行的具体参数。例如，AI 要点击一个按钮时，展示按钮的 selector 或坐标，确认是否正确。

3. 防止恶意数据外泄：检查工具输出，避免敏感信息（密码、token、个人信息）被 AI 读取并外传。如果工具返回了敏感数据，不要让 AI 写入日志或发送到外部服务器。

4. 设置 timeout：浏览器操作可能卡死，导致资源耗尽或阻塞其他任务。为每个工具调用设置合理的 timeout（如 30 秒），超时后自动取消。

5. 记录 tool usage：保留操作日志，用于审计和问题追溯。日志应包含：工具名称、调用时间、输入参数、输出结果、用户确认记录。

6. 验证 tool results：检查工具返回的截图、console log、网络请求是否符合预期。如果 AI 报告”点击成功”但截图显示按钮没被点击，需要排查问题。

服务端侧安全建议

如果你自己开发 MCP server（Playwright MCP 是官方 server，不需要你自己开发），需要遵循以下建议：

1. 输入验证：验证 URL、选择器、输入内容，防止注入攻击。例如，不要让 AI 传入恶意 URL 或 XSS payload。

2. 访问控制：限制可访问的域名、文件路径、浏览器能力。例如，禁止访问内网 IP 或敏感路径。

3. 限流：防止 AI 频繁调用工具导致资源耗尽或被目标网站封禁。设置合理的速率限制（如每分钟最多 10 次调用）。

4. 输出清洗：去除敏感信息后再返回给 AI。例如，不要返回完整的 cookies 字符串，只返回必要的部分。

---

第一次验证任务与验收清单

配置完成后，用一个简单任务验证 Playwright MCP 是否正确接入。

任务示例

让 AI 打开本地预览页 http://localhost:4321，点击导航菜单，截图并报告 console error。

分步操作：

1. 确保 Playwright MCP 已添加到你的客户端（Claude Code、Codex 或 Cursor）

2. 启动本地开发服务器（如 Astro、Next.js），确保 http://localhost:4321 可访问

3. 在 Claude Code/Codex/Cursor 中输入提示词：

   打开 http://localhost:4321，点击导航菜单中的"文章"，截图并报告页面是否有 console error。

4. 观察 AI 是否调用浏览器工具、浏览器是否启动、页面是否打开

验收清单

检查项	期望结果	如何确认
浏览器是否启动	浏览器窗口打开（headed 模式）或进程启动（headless）	观察 UI 或进程管理器
MCP server 是否连接	客户端日志显示 “Connected to MCP server”	查看客户端日志
accessibility snapshot 是否返回	AI 能找到导航菜单并点击	AI 输出包含点击动作描述
工具调用是否需审批	取决于配置，Codex 可能弹出审批对话框	观察客户端是否弹出审批对话框
输出目录/日志是否可查	截图、console log 等输出在 --output-dir	检查指定目录

失败场景排查

AI 不调用浏览器工具：

• 检查 MCP server 是否正确添加（查看客户端日志）
• 检查客户端是否支持 MCP Tool Search（Claude Code 默认启用）
• 检查 Node.js 版本是否 >= 18

浏览器打开但找不到按钮：

• Playwright MCP 操作 accessibility tree，不是截图。如果网页缺少语义化标签或 ARIA 属性，AI 可能无法识别
• 检查网页的 HTML 结构，确保按钮有可访问的标签或 role 属性
• 或使用 --snapshot-mode 参数调整快照详细程度

浏览器启动但立即关闭：

• 可能是 headless 模式或脚本执行完毕
• 检查客户端日志，确认浏览器是否正常启动和关闭
• 如果使用 headed 模式，浏览器窗口应该保持打开直到 AI 报告完成

---

与 Playwright CLI/SKILLS 的取舍

Microsoft 官方 README 明确指出：coding agents 在高吞吐代码工作流中可能更适合 CLI + SKILLS，因为 MCP 会把工具 schema 和 accessibility tree 带入上下文，占用 token。MCP 更适合需要持久状态、丰富 introspection、持续浏览器上下文的探索式自动化、自修复测试或长任务。

场景对照表

场景	推荐 Playwright MCP	推荐 Playwright CLI + SKILLS
探索式自动化、自修复测试	✅ 适合	❌ 不适合
长任务、需要持久浏览器上下文	✅ 适合	❌ 不适合
高吞吐代码工作流	❌ 不适合（上下文占用大）	✅ 适合
需要最小上下文占用	❌ 不适合	✅ 适合
已经在使用 MCP client（Claude Code/Codex/Cursor）	✅ 适合	❌ 不适合

本篇不展开 SKILLS 的具体用法，后续文章会讲 Codex 浏览器验证实战。

---

总结与下一步

这篇文章覆盖了 Claude Code、Codex、Cursor 三种客户端的 Playwright MCP 配置，第一次验证任务的验收清单，以及安全边界：browser_run_code_unsafe 的 RCE 风险、Profile 模式的登录态保存、--allowed-origins 不是安全边界。

配置差异总结

• Claude Code：用 claude mcp add 命令或 .mcp.json 项目级配置，默认启用 Tool Search
• Codex：用 codex mcp add 命令或 config.toml 配置，支持 approval_mode 控制高风险工具
• Cursor：通过 Settings UI 配置，步骤与前两者不同

下一步建议

• 需要工具选型横评：看 Browser Use vs Stagehand vs Playwright MCP：2026 年 AI 浏览器工具选型指南
• 需要登录态管理：看 AI 浏览器登录态管理
• 需要前端测试：看 Playwright 前端测试与验证
• 需要 Codex 浏览器验证：看 Codex 浏览器验证实战
• 需要托管基础设施：看托管浏览器基础设施
• 需要安全攻防：看 AI 浏览器安全攻防

如果你刚配置好 Playwright MCP，先跑一遍 localhost:4321 的验证任务，确认浏览器能启动、AI 能调用工具、截图能输出到指定目录。如果遇到问题，按 FAQ 排查，或检查 Node.js 版本、客户端日志和 MCP server 连接状态。