Playwright MCP

Microsoft 维护的 Playwright MCP server，让 LLM 通过可访问性快照和结构化工具操作网页。

这个能力解决什么问题

浏览器 Agent 最怕两件事：只看截图导致定位不稳定，或者直接写 Playwright 脚本导致交互太硬。Playwright MCP 解决的是给 MCP 客户端一组结构化浏览器工具，让模型基于 accessibility tree 读取页面、选择元素、点击、输入、等待、截图、看网络和控制台，而不是靠视觉猜坐标。

核心逻辑

输入是 MCP 客户端发出的浏览器工具调用，例如导航 URL、获取页面 snapshot、点击某个 ref、输入文本或保存 PDF。处理层由 MCP server 维护 Playwright browser context，把页面转成 accessibility snapshot，给可交互元素生成 ref；模型后续行动必须带着人类可读元素描述和精确 ref 执行。输出是新的页面状态、结构化 snapshot、截图/PDF/console/network 结果，或工具执行错误。

技术结构

• MCP Server：通过 npx @playwright/mcp@latest 接入 VS Code、Cursor、Claude Desktop、Goose、Codex、Gemini CLI 等 MCP host。
• Accessibility snapshot 优先：默认用 Playwright 的 accessibility tree，减少 token 和视觉误判。
• 工具族：导航、点击、拖拽、hover、type、select、按键、等待、上传文件、处理 dialog、截图、PDF、网络请求、控制台消息等。
• 状态配置：支持 persistent profile、isolated context、storage state、extension 连接已有浏览器、user-data-dir、init script/page 等初始状态方式。
• 安全与运行参数：allowed/blocked origins、file access、permissions、headless、proxy、snapshot mode、output dir、timeout 等参数把浏览器权限做成启动配置。

为什么值得参考

它的设计亮点是把“可见网页”转换成“模型可推理的结构化状态”。相比截图流，accessibility snapshot 更适合工具调用：元素有语义和 ref，动作可以复现，测试和自动化都更稳定。README 还清楚区分了 MCP 与 Playwright CLI：MCP 适合持续浏览器上下文和探索式循环，CLI+Skill 更适合高吞吐编码任务。

为什么不建议直接套用

MCP 会把工具 schema 和页面快照带进上下文，复杂页面会消耗大量 token；对编码 agent 来说，官方 README 也提示 CLI+Skill 可能更高效。浏览器 profile 有并发限制，同一 persistent profile 不能被多个实例同时使用。若允许 file access、extension 或已有登录态浏览器，权限边界会迅速变宽，必须用 isolated context、storage state 和域名白名单收紧。

如何改造成自己的版本

内部可把它作为底层浏览器 adapter，而不是直接暴露全部工具。先定义 6 个高频动作：打开页面、读取结构、点击、输入、截图、取 console/network；把域名白名单、profile 模式、输出目录、超时写死在配置里。再在 Skill 层包装任务模板，例如“登录态 QA”“表单回归”“页面截图验证”，让 agent 不需要知道所有 Playwright MCP 参数。

适用场景

• 网页 QA、表单填写、探索式自动化、长浏览器会话。
• 需要基于 DOM/accessibility 结构定位元素。
• MCP 客户端已经是主要 Agent 运行环境。

不适用场景

• 高吞吐代码任务更适合 Playwright CLI/脚本。
• 页面极复杂且 snapshot 过大，token 压力明显。
• 不能接受浏览器登录态或本地文件权限暴露。

参考信息

• 原项目：playwright-mcp
• 作者：microsoft
• 相关概念：[[MCP]]、[[浏览器自动化]]、[[可访问性树]]
• 相关卡片：保守留空