安装 Playwright MCP，每个 Agent 只需要一条命令。那为什么还会有配置教程：因为大家遇到的并不是安装报错，而是作用域和措辞上的意外，没人提醒的话，每一个都要花掉一小时。
本文给出可直接复制的配置步骤，覆盖 Claude Code、Cursor 和 Codex，还整理了三个值得提前了解的常见报错，以及大多数配置教程都会跳过的一点：有三种情况其实一开始就不该装 Playwright MCP。
先说前提，免得下面哪一步让你意外：PATH 中有 Node.js 18 或更高版本，一个上面列表里的 Agent，大约五分钟。这个服务器本身是微软出品，免费，基于 Apache-2.0 开源；这里不需要账号，也不需要 API Key。
五分钟装好，一分钟判断什么时候不该装。
Playwright MCP 与 Chrome DevTools MCP、ego (lite) 有什么区别？
当 Agent 需要结构化的无障碍树快照（accessibility snapshot）和可重复的 Playwright 控制浏览器时，Playwright MCP 最合适。当你需要连接到屏幕上已经打开的 Chrome 窗口时，Chrome DevTools MCP 是更好的调试路径。当需求是复用现有登录态、又不接管你的窗口时，ego (lite) 是更好的日常工作路径。它们是不同的控制面，不是同一个工具可以互换的版本。
| 路径 | 浏览器状态 | 最擅长 | 检查成本 |
|---|---|---|---|
| Playwright MCP | 默认拥有自己的持久化配置文件（Profile）；也提供隔离模式 | DOM 感知的探索、快照和跨浏览器脚本 | 快照上下文和会话设置 |
| Chrome DevTools MCP | 可以通过自动连接附加到正在使用的 Chrome 配置文件（Profile） | 性能追踪、控制台诊断和当前标签页调试 | Chrome 144+、远程调试端口和共享窗口 |
| ego (lite) | 在隔离的 Space（隔离空间）中继承已登录的网站 | 后台、并行、已认证的 Agent 任务 | 本地安装；无需 MCP 或调试端口设置 |
决策规则很简单：需要全新、可检查的浏览器上下文时选 Playwright MCP；需要调试你已经在看的页面和性能状态时选 Chrome DevTools MCP；当有价值的状态是你现有的登录态、且 Agent 应该在你旁边工作时选 ego (lite)。如果 Token 用量是瓶颈，下面链接的 CLI 对比比继续添加 MCP 工具更适合作为起点。
如何在 Claude Code 中配置 Playwright MCP？
在你的项目目录中运行一条命令：
claude mcp add playwright npx '@playwright/mcp@latest'验证一下：启动 Claude Code，运行 /mcp，然后选择 playwright。你应该能看到工具列表（当前版本有二十多个工具：browser_navigate、browser_click、browser_snapshot、browser_take_screenshot 等）。然后让它执行一个真实操作：
Use playwright mcp to open a browser to example.com应该会打开一个可见的 Chrome 窗口。注意“use playwright mcp”这个措辞：首次运行时 Claude 有时会去用 Bash 和原生 Playwright，而不是 MCP 工具，明确点名工具可以把它引导到正确的路径。Simon Willison的文章记录了这一点，以及下面的作用域细节。
如果你更喜欢直接编辑配置，Claude Code 存储的等效条目长这样（按项目，位于 ~/.claude.json 内）：
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
如何在 Cursor 中配置 Playwright MCP？
打开 Cursor Settings，进入 MCP，点击 Add new MCP Server，然后填入标准配置块（同一段 JSON 在 VS Code、Windsurf 和大多数 MCP 客户端里都能用）：
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}验证方法：服务器应该在 MCP 设置列表里显示绿色状态，并列出它提供的工具。然后在对话中让 Agent 打开一个页面并抓取快照，弹出提示时批准这次工具调用。如果服务器显示红色，几乎都是 Node 的问题：在 Cursor 继承的 shell 里检查 node --version 是否为 18+。
有两个放置位置的细节，能帮 Cursor 用户省下一次莫名其妙的重启：配置可以放在单个项目里（仓库根目录的 .cursor/mcp.json），也可以放在全局（~/.cursor/mcp.json），在该工作区中项目文件优先。Playwright 文档还提供了面向 Cursor 的一键安装 deeplink，如果你完全不想碰 JSON 的话可以用它。
如何在 Codex 中配置 Playwright MCP？
Codex 有专门的添加命令：
codex mcp add playwright npx "@playwright/mcp@latest"这条命令会把服务器写入 Codex 的配置（~/.codex/config.toml）。用 codex mcp list 验证，然后让 Codex 导航到某个页面并读取内容。和 Claude Code 一样，第一次使用时要点名这个工具，否则 Agent 会自己用 shell 命令凑合。
如果你手动管理配置文件，等价的 TOML 写法如下：
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]有三个 flag 在所有 Agent 上都值得了解，追加到 args 数组里即可：--headless 用于 CI 和后台运行（默认是有头模式），--browser=firefox 或 webkit 或 msedge 用于跨浏览器测试，--isolated 用于让每个会话都从干净的浏览器配置文件（Profile）启动，而不是复用持久化的那个。另外还有共享服务器模式（npx @playwright/mcp@latest --port 8931），适合多个客户端通过 HTTP 驱动同一个浏览器。
最常见的三类报错是什么？
Reddit 和 GitHub 上大多数配置求助帖，问题都出在下面三类故障上。每一个都有三十秒就能搞定的修复方法。
| 现象 | 原因 | 修复方法 |
|---|---|---|
| Agent 在 Bash 里写 Playwright 脚本，而不是调用 MCP | 模型选了它更熟悉的工具，它读不懂你的意图 | 在会话的第一条提示里明确说“use playwright mcp” |
| 明明装了服务器却找不到 | 作用域按目录划分：配置写在你执行 add 命令时所在的文件夹下 | 在当前项目里重新添加，或者用 --scope user 做全局安装 |
| 第一次导航就失败，报浏览器启动错误 | npx 拉取的运行时没有对应的浏览器二进制文件 | 让 Agent 运行它的 browser_install 工具，或者自己执行 npx playwright install chromium |
如果这三类都排除了还是跑不起来，先检查 Node（要求 18+），再查别的；这一类里剩下的 GitHub issue 几乎都能在这里找到答案。
跑通之后，用下面三条初始提示可以端到端验证配置，按实用性递增排列：“use playwright mcp to open example.com and tell me the main heading”（验证导航和快照），“open our staging site,用一个垃圾邮箱填写注册表单，并报告校验错误”（验证表单交互），以及“open the pricing page, take a screenshot, and list every plan name you can see”（验证截图加数据提取）。
如果这三条都通过，剩下的就只是提示词的问题了，而真正要问的是这个工具到底适不适合你的工作负载，这正是下一节要讲的。
什么情况下应该跳过 Playwright MCP？
接下来这部分，能让你下个月不用再重装一遍。对于在公开页面上做短时间的探索性会话，Playwright MCP 是合适的默认选择。但有三种情况会打破这个默认，而每一种都指向形态不同的工具：
| 你的情况 | 为什么 MCP 形态不合适 | 改用 |
|---|---|---|
| 对 Token 敏感：任务长、预算紧 | 每个操作都会返回一次页面快照；实测运行达到每个测试 89K-114K Token，而通过 CLI 只需 24K-27K | 官方 Playwright CLI，或者 ego (lite)：一个 Agent 浏览器，它返回紧凑的语义快照，带有稳定的元素引用，并把多个操作合并成一次页面内 JavaScript 执行，以减少往返次数 |
| 需要登录你自己账号才能完成的任务 | MCP 会启动一个全新的浏览器配置文件（Profile），没有 Cookie；每次认证都得你自己写脚本处理 | ego (lite)：你登录过的每个站点都保持登录态，Agent 直接继承这个状态 |
| 多个浏览器任务并行 | 默认只有一个串行的浏览器会话；并行的 Agent 会互相干扰 | ego (lite) 的 Space（隔离空间）：你的 AI Agent 可以同时跑 100+ 个浏览器任务，每个任务都有自己的工作区，不会和你正在用的标签页冲突 |
在 ego (lite) 那几行里，形态上的差异值得再补一句：它是一个你也能用来浏览的完整 Chromium，而不是只能跑脚本的运行时。
它的安装配置也符合本指南“复制粘贴即可”的风格：一条命令就能装好 ego-browser skill，或者用一句提示词把整件事交给你的 Agent。
npx skills add citrolabs/ego-litePaste into your agent
Set up ego lite for me: https://github.com/citrolabs/ego-lite Read `skills/ego-browser/references/install.md` and follow the steps to install ego lite.
在我们公开的基准测试中，相比一次执行一条命令的方式，这种组合完成同样的任务，执行轮次减少 44%，工具调用减少 35.5%，成本降低 21.6%。测试框架和数据都公开在ego-browser-benchmark-framework 仓库。如果你每周都要在已登录的站点上处理日常任务，先把那套配置好，把 Playwright MCP 留给它擅长的公开页面探索。
下载 Mac 版 ego (lite) ，或者查看 它与 Playwright MCP 的逐项功能对比.
FAQ
如何把 Playwright MCP 添加到 Claude Code？
在项目目录下运行 claude mcp add playwright npx '@playwright/mcp@latest'，然后在 Claude Code 里用 /mcp 验证。如果希望每个项目都能用，加上 --scope user。
Playwright MCP 安装和使用免费吗？
免费：Apache-2.0 许可，由 Microsoft 维护，通过 npm 安装。真正的运行成本是 Token 消耗，在长任务上这正是上文“何时跳过”一节存在的原因。
Playwright MCP 支持有头模式和无头模式吗？
默认是有头模式，你可以直接看到浏览器在做什么；在 CI 或后台运行时，在 args 里加上 --headless 即可。跨浏览器参数（--browser=firefox、webkit、msedge）在两种模式下都可用。
如何更新或卸载 Playwright MCP？
使用 @latest 标签时更新是自动的：每次启动服务器，npx 都会拉取最新版本。卸载与安装对应：claude mcp remove playwright、codex mcp remove playwright，或者从 Cursor 的 mcp.json 中删除对应配置块。关于自动更新有一点需要注意：issue#889 （官方仓库）记录了一个小版本把 Token 用量放大了 6 倍，所以如果成本一夜之间暴涨，就在 args 里固定版本。
Playwright MCP 能用我已登录的 Chrome 浏览器配置文件（Profile）吗？
不要用你日常那个配置文件。它默认使用自己独立的持久化配置文件，而把工具指向你真实的 Chrome 配置文件，会遇到配置文件锁和会话冲突。如果需求是继承你现有的登录态，那 ego (lite) 就是对应的方案：你只需导入一次 Chrome 的配置，Agent 就从那个已登录状态开始工作，共享多少由你决定。
