🎭 Playwright MCP 安装指南

一句话总结：Playwright MCP（@playwright/mcp）是微软官方的浏览器自动化 MCP server，用结构化可访问性快照（accessibility tree）让 agent 操作网页，无需视觉模型。OpenCode 和 Harness 都能接入。

---

是什么

Model Context Protocol (MCP) server，用 Playwright 提供浏览器自动化。通过结构化可访问性快照让 LLM 与网页交互，绕过截图或视觉调优模型。

特点：快而轻（走 accessibility tree 不是像素）；LLM 友好（纯结构化数据，不需要视觉模型）；确定性工具应用（避免截图方案的歧义）。

⚠️ 官方建议：如果你是编码 agent，微软更推荐用 Playwright CLI + SKILLS 而不是 MCP——CLI 更省 token（不把庞大的工具 schema 和冗长 accessibility 树塞进模型上下文）。MCP 更适合要持久状态、富内省、对页面结构迭代推理的 agent 场景（探索式自动化、自愈测试、长时自主工作流）。

前置要求：Node.js 18+；任一 MCP 客户端（VS Code、Cursor、Windsurf、Claude Desktop、Goose、Grok、Junie、OpenCode、Harness 等）。

---

安装（OpenCode）

在 ~/.config/opencode/opencode.json 加一个本地 MCP：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp@latest"],
      "enabled": true
    }
  }
}

改完重启 OpenCode。

通用 MCP 配置写法：command: npx + args: ["@playwright/mcp@latest"]。官方也提供 npm 安装 npm i -g @playwright/mcp 再在配置里指向可执行文件，但 npx 方式最省事。

---

安装（Harness / DSH）

Harness 走 Cordis 插件方式，在 $DSH_HOME/settings.yaml 里加一条 @deepseek-ai/dsh-mcp-client：

- id: mcp-playwright
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: playwright
    transport: stdio
    command: npx
    args: ['@playwright/mcp@latest']

启动后工具以 mcp__playwright__<tool> 形式出现。

---

常用选项

Playwright MCP 支持若干配置参数（通过 CLI flag 或环境变量）：

选项	说明
--headless	无头模式（默认 true）
`—browser <chromium	firefox
--user-data-dir <path>	持久化浏览器 profile，保留登录态
--isolated	每个会话独立浏览器上下文
--device <name>	模拟移动设备

加在 args 里即可，例如 OpenCode："command": ["npx", "@playwright/mcp@latest", "--headless", "--browser", "chromium"]。

---

排错

报错	处理
浏览器没装	首次 npx @playwright/mcp 会自动下载对应浏览器；否则 npx playwright install chromium
工具没出现	改配置后重启 agent
沙盒被拦	页面权限、下载等可能被环境拦，检查 agent 的权限/白名单设置

---

状态记录

• 2026-10-03：初版。整理 OpenCode / Harness 接入、CLI vs MCP 取舍、常用选项。未实测——按官方 README 整理，未在 OpenCode / Harness 里实际跑过。

🔗 相关

• Superpower 安装指南 · Comet 安装指南 · CodeGraph MCP 安装指南 — 同批安装指南
• 官方仓库：microsoft/playwright-mcp
• 官方文档：Playwright · Playwright CLI + SKILLS