如果你已经把 Playwright MCP 添加到 Claude Code，却仍然打不开页面，那么一上来就重装所有东西通常不是最好的做法。大多数 MCP 安装配置问题都出在几个常见原因上：project 级别的 MCP 服务器还没有通过审批，启动命令写错了，或者缺少所需的浏览器二进制文件。
先运行 /mcp，检查服务器是否已连接、Playwright 工具是否可用。然后让 Agent 打开一个页面。这样有助于判断问题出在 MCP 连接、Playwright 本身，还是浏览器环境，而不必反复修改一份可能本来就正确的配置。
但打开页面只是第一步。真实的浏览器任务往往涉及搜索、打开多个页面、在不同来源之间切换，并根据页面上出现的内容决定下一步怎么做。比如排查一个报错时，Agent 可能需要查看搜索结果、打开多个相关讨论、对比别人报告的环境和报错信息，再评估各种修复建议，最后判断哪一个值得尝试。
使用 ego (lite) 时，Agent 可以让这些页面保持打开，并在一个独立的浏览器 Space（隔离空间）里继续工作，不会打断你正在使用的浏览器窗口。你可以随时进入该 Space，查看 Agent 找到了什么，或者在需要人来判断时接管操作。
本文先讲如何在 Claude Code 中配置 MCP，以及如何排查常见的 Playwright 和浏览器问题。然后用同一个排查任务，演示另一种浏览器工作流。MCP 服务器显示“connected”只说明工具可用。真正重要的是，Agent 能否实际用这些工具完成接下来的浏览器任务。
MCP 服务器能为 Claude Code 增加什么能力？
Claude Code 自带内置工具，但 model context protocol 服务器可以让你添加它默认没有的具名能力，比如浏览器、数据库或 SaaS API。Claude Code 官方文档把这类服务器描述为连接外部工具和数据源的方式，用 claude mcp add 添加，并在会话中用 /mcp 管理。
协议本身定义在modelcontextprotocol.io，传输方式和能力都在那里规定。
这些命令背后的 CLI 参考是Claude Code MCP 官方文档。
连接通过 JSON-RPC 2.0 进行。Claude Code 充当 host，MCP 服务器作为子进程（stdio）或可访问的端点（HTTP）运行，每个工具都带有名称、描述和输入 schema，模型在调用前会先读取它。正因为有这份 schema，配置错误的服务器才会表现为工具缺失，而不是直接崩溃：连接建立了，但没有发现任何工具。
服务器不是插件，也不是扩展程序。插件可以打包一个 MCP 服务器，但直接添加服务器会往你的 MCP 配置里写入一条记录。当同一个工具出现两次，一次来自插件、一次来自你自己的配置，且参数不同时，这个区别就很关键。
local、project、user 三种 scope 该怎么选？
Claude Code 按 scope 解析 MCP 服务器，而 scope 同时控制两件事：配置存放在哪里，以及还有谁能加载它。选择依据应该是这个服务器该如何流转，而不是凭习惯。
| Scope | 存放位置 | 谁可以看到 | 最适合的场景 |
|---|---|---|---|
| local（默认） | 项目路径下的 ~/.claude.json | 仅当前项目，不共享 | 只想在某个仓库里用、别处都不用的私有服务器。 |
| project | 项目根目录下的 .mcp.json | 仅当前项目，通过版本控制共享 | 整个团队都需要、固定在一份配置里的服务器。 |
| user | ~/.claude.json | 你的所有项目，但不共享 | 一个你想在任何地方都能用的个人服务器。 |
当同一个服务器名称出现在多个 scope 中时，Claude Code 会整体采用优先级最高的那一条。local 高于 project，project 高于 user，并且胜出的条目不会与其他条目合并。一条过期的 user scope 条目可能会悄悄遮蔽 project 条目。
如何添加并验证 MCP 服务器？
用 claude mcp add 添加一个本地 stdio 服务器，使用 -- 把 Claude Code 自身的 flag 与它将启动的服务器命令分隔开。双横线会确保其后的内容不会被解析为 Claude Code 的选项。
claude mcp add --scope project playwright -- \
npx --yes @playwright/mcp@latest --isolated对于远程 HTTP 服务器，传入 transport 和 endpoint。一个带有 url 但没有 type 的 JSON 条目属于配置错误，所以手写配置时要把 type 写清楚。
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp验证与添加是两回事。claude mcp list 会显示每个服务器的健康状态，claude mcp get 接收服务器名称，并在存在失败时打印失败详情。在会话内，/mcp 会列出已连接的服务器、它们的工具数量，以及任何需要认证或批准的服务器。
claude mcp list
claude mcp get playwright一个显示 Connected 但没有暴露任何工具的服务器，或者一个显示 Failed to connect 并带有错误码的服务器，都没有通过验证。保存配置只是检查的开始，而不是结束。
project scope 的服务器什么时候会要求审批？
来自 .mcp.json 文件的 project scope 服务器，会在交互式 Claude Code 会话首次尝试使用它们时提示批准。这是有意为之：一个被提交的文件不应该仅仅因为存在于仓库中，就悄悄把浏览器控制权交给 Agent。
非交互式运行会改变规则。在 claude -p、Agent SDK 会话和云会话中，没有提示可以显示，所以 Claude Code 会不加询问地加载 project scope 服务器。这就是为什么你在本地信任的配置，在 CI 中可能成为更大的暴露面。
| 运行类型 | 批准行为 | 需要注意什么 |
|---|---|---|
| 交互式会话 | 在使用 project 服务器前提示 | 待批准是一种信任状态，不是崩溃。 |
| claude -p / Agent SDK / 云 | 不加提示地加载 project 服务器 | 被提交的 .mcp.json 会在没有人工把关的情况下执行。 |
| 不受信任的工作区 | 仓库中签入的批准会被忽略，直到你信任该文件夹 | 服务器会保持 Pending approval，直到你运行 claude 并接受。 |
如果你永远不想加载某个特定的 project 服务器，把它加入 disabledMcpjsonServers。如果你想只从你显式传入的服务器开始，使用 --strict-mcp-config。两者都是刻意的控制手段，而不是用来掩盖信任提示。
Playwright MCP 到底需要哪些修复方法？
Playwright MCP 是人们接入 Claude Code 最常见的浏览器服务器，它的故障集中在三个地方。每一处都有比重新安装更好的修复方法。
这里每个示例中的服务器都是microsoft/playwright-mcp，它的工具列表和未解决问题都在那里。
它封装的 API 文档在playwright.dev。
如果你还在纠结该接入哪个浏览器服务器，Claude Code 的浏览器 MCP 对比对各选项做了排名。
如果你是从一台干净的机器开始，而不是修复已有的服务器，Claude Code 与 Cursor 的 Playwright MCP 安装配置指南按顺序讲了安装和注册。
Windows：npx 会破坏 stdio 管道
在 Windows 上，npx 是 npx.cmd，一个批处理包装器，而 Claude Code 启动它时不带 shell。MCP 依赖的 stdio 管道永远连不上，服务器会报 Connection closed。文档给出的变通方法是把命令包一层，让 cmd 来运行它，或者直接调用 node 指向该包的 cli.js。
claude mcp add --scope user playwright -- cmd /c npx @playwright/mcp@latest{
"mcpServers": {
"playwright": {
"command": "node",
"args": ["C:\\path\\to\\node_modules\\@playwright\\mcp\\cli.js"]
}
}
}工具缺失或包名过时
正确的包是 @playwright/mcp。旧的 @modelcontextprotocol/server-playwright 名称已弃用，而 @executeautomation/playwright-mcp-server 是另一个社区项目。如果连接打开了但没有工具出现，请确认 Claude Code 实际启动的是哪个包，而不是你以为自己输入的那个。
Playwright MCP 还需要它的浏览器二进制文件。如果服务器启动了但启动浏览器失败，运行 npx playwright install，在 Linux 或 Docker 中再加上 npx playwright install-deps。官方文档给出的 Node.js 要求在页面之间不一致，README 里是 18 或更新版本，getting-started 指南里是 20 或更新版本，所以请核对你眼前的页面和你的 node --version。
服务器挂掉后再也回不来
Claude Code 不会自动重连 stdio 服务器。当子进程挂掉时，服务器会被标记为 failed，你需要通过 /mcp 手动重连。如果是浏览器标签页崩溃或笔记本休眠在任务中途杀死了你的服务器，修复方法是重连，而不是重装。
什么时候该从 MCP 换成 CLI 或真实浏览器？
当你想要 Agent 循环内的结构化工具、带返回快照的浏览器操作，或者一个 Claude Code 能按名字推理的工具时，就继续用 MCP。当任务是 shell 形态的、一个脚本、一个保存的输出文件，或者一次你想原样重跑而不经过 Agent 循环的运行，就转向 Playwright CLI。
针对已有 Chrome 会话的同类故障，Chrome DevTools MCP：安装配置、已有会话与修复方法做了完整讲解。
服务器连上之后也会消耗上下文；如何减少 MCP Token 用量讲了这一权衡。
当已获授权的登录态是硬性要求时，就该换用真实浏览器路线。全新的隔离 Playwright 浏览器配置文件（Profile）不会继承你日常使用的 Chrome 会话，单靠某个 MCP 参数也改变不了这一点。
如果想了解 Agent 可以走哪些更广泛的浏览器路线，给 Claude Code 配浏览器的五种方式一文按安装配置成本和登录态行为做了对比。
我们在同一台机器上用其中两条路线跑了同一个调研提示词：一条是配置好的 Playwright MCP 服务器，另一条是由 ego-browser CLI 驱动的独立浏览器 Space。提示词要求找出仓库 README、安装命令、Node.js 版本要求，以及最多三个与Connection closed、npx 和 stdio 相关的问题，每个问题都要给出环境、现象和解决办法。两次运行最终都报告了三个问题，但报告的并不是同样三个。
MCP 路线先读仓库，确认了 README 和 Node.js 18 的要求，然后进入 Issues 标签页。接下来它把每个 issue 当作保存下来的 DOM 转储来读，再用 shell 文本工具把字段提取回来。到 3 分 40 秒时它才打开第二个 issue，整轮运行在约 7 分 15 秒结束，报告的是 1385、1540 和 1611。
真实浏览器路线直接在页面内查询实时 DOM，而不是把它转储出来，并额外打开一个 Space，让搜索结果和 issue 页面同时保持可见。到 3 分 03 秒时它已经确认了一个候选，4 分 11 秒时读到了第三个 issue 的仓库公告。它报告的是 658、1540 和 1385。
两次结果的重合项是 1540 和 1385。但差异比重合更重要：658 是那个承载着一条配置解决办法的讨论帖，而且有多位报告者确认有效，MCP 那次运行却没有把它翻出来。真实浏览器那次运行还因为内容太单薄而放弃了一个候选，而 MCP 那次运行保留了一个 issue，可该 issue 的报告者自己已经以“不适用于该仓库”为由把它关闭了。这是信息取材上的差异，不是速度差异，也是选择路线时真正诚实的理由，而不是拿秒表比快慢。
| 本次运行中观察到的结果 | Playwright MCP 路线 | 真实浏览器路线 |
|---|---|---|
| 页面读取方式 | 把快照保存到文件，再用 shell 文本工具读回 | 页面保持打开，直接在页面内查询实时 DOM |
| 打开第二个 issue 的时间 | 3 分 40 秒 | 3 分 03 秒，并已确认一个候选 |
| 读到第三个 issue 的时间 | 5 分 45 秒时仍在读取 | 4 分 11 秒，报告已在撰写中 |
| 报告的问题编号 | 1385、1540、1611 | 658、1540、1385 |
| 是否包含可用的配置修复 | 否 | 是，见 issue 658 |
| 运行过程中可见、可中断 | 否，只有工具活动 | 是，两个 Space 同时显示在屏幕上，并带有接管控制 |
| 路线 | 它能做什么 | 它不能假设什么 |
|---|---|---|
| MCP 服务器 | 向 Claude Code 暴露具名工具和实时页面证据。 | 它不会变成一套可长期使用的测试套件，默认也不会继承个人 Chrome 状态。 |
| Playwright CLI | 运行简洁的 shell 命令，并保存快照或输出文件，供有选择地读取。 | 它无法在没有 shell 和文件系统访问权限的客户端中运行。 |
| 真实浏览器路线 | 在独立浏览器工作区中操作，使用符合条件且已获批准的状态。 | 它不提供 Playwright Test 的 fixture、断言、网络 mock 或 trace。 |
完整的界面与上下文成本对比，请阅读Playwright MCP vs CLI。本文只聚焦 Claude Code 配置和 Playwright 修复方法。
ego (lite) 适合用在哪里，又不适合用在哪里？
ego (lite) 是另一条执行路线，适用于问题不在 MCP 连接本身的任务。它通过 ego-browser skill 在独立的 Space 中驱动真实 Chromium 浏览器，并能复用符合条件的用户授权状态。当任务需要登录态、可见的操作步骤，或者需要人在运行中途接管时，这一点很关键。
整个工作流是一轮 JavaScript 执行，而不是一长串 MCP 工具调用。你只需打开一次 Space，然后把原本要逐个浏览器操作执行的检查批量跑完：
ego-browser nodejs <<'EOF'
const task = await taskSpace("article-qa");
for (const [slug, url] of Object.entries({
home: "https://lite.ego.app/",
mcpConfig: "https://lite.ego.app/article/claude-code-mcp-configuration"
})) {
const page = await task.newPage();
await page.goto(url, { waitUntil: "domcontentloaded" });
const report = await page.evaluate(() => ({
h1: document.querySelectorAll("h1").length,
horizontalOverflow: document.documentElement.scrollWidth > innerWidth
}));
console.log(slug, report);
}
await task.finish({ keep: [] });
EOF这种模式已经跑在我们自己的发布流水线里。2026 年 9 月 10 日，我们在一个 Space 中同时打开八个文章页面，一起检查桌面端和 390 像素移动端布局：canonical、语言标签、H1 数量、标题层级顺序、图片加载与 alt 文本、锚点目标、代码溢出和横向溢出，然后点击文章目录，确认目标标题进入了视口。
它不是 MCP 服务器，不是 Playwright Test 运行器，也不是 Claude Code 插件。当 Agent 需要一个可检查、带有已批准实时状态的浏览器工作区时，用它。断言密集的 E2E 套件、网络 mock、trace 产物和无头 CI，仍然交给 Playwright。
FAQ
如何给 Claude Code 添加 MCP 服务器？
使用 claude mcp add，并用 -- 把 Claude Code 的 flag 与服务器命令分开。按需显式加上 --scope project 或 --scope user，然后用 claude mcp list 或 /mcp 验证。
Claude Code 把 MCP 配置存在哪里？
local 和 user scope 存在 ~/.claude.json。project scope 存在项目根目录的 .mcp.json 文件里，可以提交到版本控制。
为什么 Claude Code 提示 Pending approval？
project scope 的 MCP 配置在交互式会话中需要信任批准。在受信任的项目里打开 Claude Code，检查命令，然后批准。
在 CI 中，project 服务器会要求批准吗？
不会。claude -p、Agent SDK 和云端会话无法弹出提示，因此会直接加载 project scope 的服务器。请把已提交的 .mcp.json 视为交互式使用之外的更大暴露面。
为什么 Playwright MCP 在 Windows 上会报 Connection closed？
Windows 上的 npx 是 npx.cmd，这是一个批处理包装脚本，Claude Code 在不经过 shell 的情况下无法使用它的 stdio 管道。用 cmd /c 包住命令，或者直接调用 node 执行该包的 cli.js。
Playwright MCP 正确的包名是什么？
@playwright/mcp 是官方包。旧的 @modelcontextprotocol/server-playwright 名称已废弃，@executeautomation/playwright-mcp-server 是另一个社区项目。
Playwright MCP 需要哪个 Node.js 版本？
官方页面说法不一致：README 写的是 18 或更高，getting-started 指南写的是 20 或更高。先运行 node --version，并确认你实际在看的是哪个页面，再决定信哪个。
Playwright MCP 会使用我现有的 Chrome 登录态吗？
默认不会。浏览器状态取决于 isolated 模式、user-data 目录、storage state，或者你另外配置的真实浏览器路径。
在 Claude Code 中该用 MCP、CLI 还是真实浏览器？
需要在 Agent 循环里使用结构化浏览器工具时用 MCP。面向 shell、产出文件的任务用 CLI。当已批准的登录态是硬性要求时，走真实浏览器路径。
ego (lite) 能替代 Playwright MCP 吗？
不能作为 MCP 集成的直接替代品。ego (lite) 是一个独立的 Chromium 浏览器，为 Agent 提供自己隔离的 Space，并继承你现有的登录态，因此它覆盖的是那些 MCP 服务器连接正常、但背后的浏览器会话才是瓶颈的任务。它不是 MCP 服务器，也不替代 Playwright MCP。
