Claude Code 浏览器 MCP

核心摘要

实际判断并不复杂：当 Claude Code 必须理解并操作渲染后的网页界面时，浏览器 MCP 很合适；但要想稳定，任务必须足够具体，而且每一步都要有可观察的检查点。如果同样的结果可以通过稳定 API 获得，应优先用 API 完成结构化步骤，只把浏览器留给界面专属操作或最终视觉验证。

选择并连接浏览器 MCP 服务器

先定义浏览器任务，再选择服务器

“使用浏览器”还不能算明确需求。先写清楚 Claude Code 要完成的是公开网页调研、登录后操作、表单填写、文件下载、网络请求检查、截图取证，还是生成可重复运行的测试。基于 Playwright 的本地服务器适合受控的开发任务；如果需要一次性浏览器、远程执行或会话级配置，托管会话可能更省事。浏览器扩展可以复用已有账号状态，但也会把更多个人数据和权限带入任务范围。

比较真正影响稳定性的能力

• 页面检查方式：优先选择能返回语义角色、可访问名称、文本和结构化快照的方案，不要只依赖坐标点击。
• 会话机制：明确每次任务需要全新会话、持久化 Cookie、指定配置文件，还是远程会话 ID。
• 证据能力：确认服务器能否返回当前网址、页面文本、截图、控制台输出、下载结果或网络信息，以便证明任务完成。
• 控制边界：检查是否支持域名限制、权限提示、有头或无头模式、超时设置以及主动终止会话。
• 运维适配：评估安装复杂度、浏览器依赖、版本维护情况，以及错误能否清楚反馈给 Claude Code。

如果采用 Playwright 路线，应以官方 Playwright MCP 仓库中的当前配置和工具说明为准；Claude Code 的 MCP 注册方式与权限控制，则应查阅 Claude Code 文档。首次配置应尽量精简，先跑通基本流程，再按需要加入持久化配置文件、代理、下载能力或更宽的域名范围。

先做只读冒烟测试

选择一个无需登录的公开页面，先让 Claude Code 在不点击的情况下返回最终网址、页面标题、一个可见标题和一个具名链接。随后只允许一次可逆的页面跳转，并要求它报告新网址与新标题。这样可以在接触账号凭据和可修改数据前，分别验证连接、工具发现、浏览器启动、页面检查和导航是否正常。

采用“检查—执行—验证”工作流程

把任务写成可执行约定

可靠的指令要写明起始网址、目标结果、允许访问的域名、可以执行的动作、禁止事项，以及可见的成功证据。不要只说“更新账号”，而应限定为：检查个人资料页、报告当前组织名称、给出准备替换的内容，并在保存前停止。这样智能体就有明确的停止点，人工也能先审查即将发生的修改。

重要操作前都要重新检查

• 确认当前网址，并检查是否出现意外跳转、Cookie 同意页、登录墙或中间提示页。
• 读取页面的可访问结构，通过角色、可见名称、标签或稳定的测试标识定位控件。
• 一次只执行一个边界明确的动作，然后等待预期状态变化，不要连续猜测式点击。
• 导航、刷新、弹窗变化或动态更新后，重新获取实时页面结构再继续操作。
• 记录最终网址，以及能够直接证明任务结果的页面证据。

执行前先定义成功证据

成功必须可以观察，不能仅凭“没有报错”来推断。网页调研可以用最终网址和页面字段作为证据；填写表单时，可在提交前核对各字段值；保存修改后，应同时看到确认提示，并在重新加载页面后验证数据仍然存在；视觉检查则要提前约定视口尺寸，以及截图中必须出现的组件或状态。

用五部分提示词替代模糊命令

可复用的浏览器提示词可以分成五部分：背景、结果、范围、检查点和证据。背景说明使用哪个账号、环境和起始页面；结果描述用户最终应该看到什么，而不是预先猜一串点击步骤；范围列出允许访问的域名和操作，同时明确禁止事项；检查点规定智能体必须在哪里暂停等待复核；证据则说明成功或失败后需要返回哪些信息。即使网站结构变化，这种写法仍然有效，因为它约束的是任务意图和验收方式，而不是脆弱的页面坐标。

• 背景：“使用测试环境账号，从项目设置页开始。”
• 结果：“准备好新的 Webhook 配置，并展示填写完成的表单。”
• 范围：“只访问获准域名，不要提交、删除或修改权限。”
• 检查点：“在最终保存前停止，并报告所有字段的确切值。”
• 证据：“返回最终网址、字段摘要和页面校验信息。”

处理常见浏览器故障

工具提示找不到元素时，应先重新检查页面：旧引用可能已经失效，控件也可能进入弹窗或 iframe。操作超时后，要判断页面是否仍在加载、是否等待新窗口、是否被登录状态阻断，或是否正在下载文件。不要盲目重复提交；重试前先检查确认提示、重复记录和网址变化。当流程已经稳定且需要重复执行时，应把确定性部分沉淀为正式测试；可参考相关的 Playwright MCP 指南。

安全与调试实践

区分观察、可逆操作与高影响操作

可以把浏览器操作分为三级。只读检查通常可以在允许访问的域名内直接进行；打开筛选器、起草内容、填写但不提交表单等可逆操作，应在复核点暂停；发送消息、发布、下单、接受条款、修改访问权限、上传私密文件或删除数据等高影响操作，则必须在执行前再次取得明确授权。授权提示要写清目标对象和具体内容，不能只笼统询问“是否继续”。

隔离凭据和会话状态

• 优先使用专用测试账号或浏览器配置文件，不要直接使用日常个人配置。
• 密码、API Key、恢复码和原始 Cookie 不应出现在提示词、截图或长期保留的日志中。
• 只开放任务所需域名；跳转至第三方登录站点时，应将其视为需要单独授权的新范围。
• 不可信或一次性任务使用短期会话；收集完证据后及时关闭远程浏览器。
• 上传或下载前，按确切文件名和目标位置进行复核。

保留可调试证据，但不要泄露敏感信息

有效的执行记录应包含时间、工具名称、脱敏后的输入、访问网址、状态变化、人工授权和最终证据。截图或日志需要长期保存时，应先遮盖凭据与个人字段。任务失败后，保留最后访问的网址、可见错误、可用的控制台信息，以及错误前执行的动作；这些信息通常足以区分元素定位变化、登录失效、页面时序问题、导航受阻和真实的产品故障。

QVeris 在浏览器 MCP 工具链中的作用

根据任务归属选择执行层

• 如果任务属于交互式开发过程，而且需要直接利用代码仓库上下文，可在 Claude Code 中连接本地浏览器 MCP。
• 如果智能体流程需要通过明确输入远程创建浏览器，并获得结构化会话信息，可使用 QVeris 浏览器会话工具。
• 如果同一数据或操作可以直接通过 API 完成，应优先在 QVeris 中调用 API，减少对元素定位、页面时序和视觉状态的依赖。
• 也可以组合使用：通过 API 准备结构化数据，在浏览器中完成界面专属步骤，并分别保留两层输出作为证据。

浏览器会话工具不会替你安装或配置 Claude Code 的 MCP 服务器，也不能取代权限设计和人工审批。只有当“远程创建会话”本身就是智能体流程的一部分时，它才更合适。对于围绕本地代码仓库的探索，或需要在 CI 中重复执行的测试，本地 MCP 服务器或正式的 Playwright 测试通常更简单。

明确哪些任务不该交给浏览器

不要因为信息能在网页上看到，就默认使用浏览器。如果任务涉及批量获取、类型明确的输入、可预测的错误处理，或需要长期无人值守运行，正式 API 通常更可靠；如果某项稳定断言需要在每次构建中执行，应写成代码库内的自动化测试；如果决策涉及法律含义、不可逆的资金影响、敏感个人数据或模糊的视觉判断，则应由人工复核。只有在必须读取渲染状态、操作界面专属控件或进行探索式交互时，浏览器 MCP 才真正有价值，而不是替代所有集成方式的默认方案。

常见问题