微软官方出品的基于 MCP 协议的浏览器自动化服务器，通过无障碍树快照为 LLM 提供结构化网页操控能力。
项目定位#
基于 Model Context Protocol (MCP) 的浏览器自动化服务器，利用无障碍树快照为 LLM 提供结构化、确定性的网页交互能力。当前版本 v0.0.75，由 Microsoft 官方 microsoft 组织维护，npm 包名为 @playwright/mcp，主要语言为 TypeScript (~62.2%)、JavaScript (~31.9%)，运行时要求 Node.js ≥ 18。
核心机制#
- 无障碍快照驱动：使用 Playwright 的无障碍树生成结构化页面快照，供 LLM 理解和操作网页，而非依赖像素截图。
- 无需视觉模型：纯结构化数据驱动，降低对多模态视觉模型的依赖。
- 确定性工具调用：避免基于截图方法带来的坐标或语义模糊性，提供确定性的浏览器操作反馈。
- 轻量快速：绕过重量级的截图管线，响应迅速。
浏览器与设备控制#
- 兼容 Chrome、Firefox、WebKit、MS Edge 四大主流浏览器。
- 支持通过
--device参数模拟移动设备（如 "iPhone 15"）。 - 支持通过
--proxy-server和--proxy-bypass进行网络代理控制。
运行与连接模式#
- 多种上下文模式：支持持久化 Profile、隔离上下文模式。
- 浏览器扩展连接：可连接已打开的浏览器标签页，复用已登录的会话状态。
- 双传输协议：默认使用 stdio 传输，可通过
--port启动 SSE/HTTP 独立服务端点供远程连接。 - 容器化运行：提供 Dockerfile，支持在 Docker 容器中运行。
- 代码生成：支持
--codegen typescript参数生成对应的 TypeScript 代码。
可选扩展能力（通过 --caps 启用）#
| 能力 | 说明 |
|---|---|
vision | 启用基于截图的坐标级交互 |
pdf | PDF 文件生成 |
devtools | Chrome DevTools 协议集成 |
network | 网络请求拦截与控制 |
storage | Cookie 及本地存储状态管理 |
config | 运行时动态配置 |
testing | 测试断言支持 |
客户端生态兼容#
广泛兼容 Claude Desktop、Claude Code、VS Code、Cursor、Windsurf、Goose、Cline、Copilot、Gemini CLI 等 20+ 种 MCP 客户端。
架构要点#
- 底层控制引擎：核心依赖
playwright和playwright-core（v1.61.0-alpha 系列）实现跨浏览器自动化。 - 协议层实现：基于
@modelcontextprotocol/sdk（^1.25.2）开发，封装 stdio 和 SSE 两种传输层。 - 工具分组：Core automation、Tab management、Browser installation、Configuration/Network/Storage/DevTools、Coordinate-based/PDF generation/Test assertions。
- 源码结构：CLI 入口
cli.js，库导出index.js/index.d.ts，核心实现位于src/目录。 - 专属集成：包含
.claude/skills目录，针对 Claude Code 做了特定技能集成优化。 - 测试体系：使用
@playwright/test，测试矩阵覆盖 Chrome、Firefox、WebKit 及 Docker 四种环境。 - 安全声明：Playwright MCP 本身不作为安全边界，需结合 MCP Security Best Practices 进行安全部署。
安装部署#
免安装直接运行（推荐）：
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
全局安装：
npm install -g @playwright/mcp
Docker 运行：
docker build --no-cache -t playwright-mcp-dev:latest .
docker run -it -p 8080:8080 --name playwright-mcp-dev playwright-mcp-dev:latest
独立 HTTP 服务器模式：
npx @playwright/mcp@latest --port 8931
客户端配置：
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/mcp"
}
}
}
关键命令行参数#
| 参数 | 说明 | 环境变量 |
|---|---|---|
--browser | chrome / firefox / webkit / msedge | PLAYWRIGHT_MCP_BROWSER |
--headless | 无头模式运行（默认有头） | PLAYWRIGHT_MCP_HEADLESS |
--isolated | 隔离模式，不持久化 profile | PLAYWRIGHT_MCP_ISOLATED |
--caps | 启用额外能力 | PLAYWRIGHT_MCP_CAPS |
--device | 模拟设备 | PLAYWRIGHT_MCP_DEVICE |
--viewport-size | 视口大小，如 "1280x720" | PLAYWRIGHT_MCP_VIEWPORT_SIZE |
--user-data-dir | 用户数据目录 | PLAYWRIGHT_MCP_USER_DATA_DIR |
--storage-state | 存储状态文件 | PLAYWRIGHT_MCP_STORAGE_STATE |
--proxy-server | 代理服务器地址 | PLAYWRIGHT_MCP_PROXY_SERVER |
--config | 配置文件路径 | PLAYWRIGHT_MCP_CONFIG |
--port | SSE 传输端口 | PLAYWRIGHT_MCP_PORT |
--snapshot-mode | 快照模式：full / none | PLAYWRIGHT_MCP_SNAPSHOT_MODE |
--output-dir | 输出文件目录 | PLAYWRIGHT_MCP_OUTPUT_DIR |
--timeout-action | 操作超时，默认 5000ms | PLAYWRIGHT_MCP_TIMEOUT_ACTION |
--timeout-navigation | 导航超时，默认 60000ms | PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION |
典型应用场景#
- AI 编码助手浏览器集成：让 Claude Desktop、Cursor、VS Code Copilot 等直接操控浏览器，完成网页测试、数据抓取、表单填写。
- 探索式自动化：利用持久化浏览器上下文进行长时间自主网页探索。
- 自修复测试：基于结构化无障碍快照，避免因 UI 变化导致的测试失败。
- 自动化数据采集：LLM 通过理解页面结构提取结构化数据。
- 无头/远程浏览器自动化：通过 SSE 传输在无显示环境中运行。
- 已有浏览器会话复用：通过浏览器扩展连接已打开的标签页，复用已登录会话。