Playwright MCP Server 🎭

---

Playwright MCP 服务 🎭

一个使用 Playwright 提供浏览器自动化功能的模型上下文协议服务。此服务可让大模型与网页交互、截取屏幕截图、生成测试代码、抓取网页内容，并在真实浏览器环境中执行 JavaScript。

✨ v1.0.10 新功能

🎯 设备模拟，支持 143 种真实设备预设！

只需一条简单命令，即可在真实设备配置上测试 Web 应用：

// Test on iPhone 13 with automatic user-agent, touch support, and device pixel ratio
await playwright_resize({ device: "iPhone 13" });

// Switch to iPad with landscape orientation
await playwright_resize({ device: "iPad Pro 11", orientation: "landscape" });

// Test desktop view
await playwright_resize({ device: "Desktop Chrome" });

支持 AI 助手使用自然语言：

• “在 iPhone 13 上测试”
• “切换到 iPad 视图”
• “旋转为横向”

**支持 143 种设备：**iPhone、iPad、Pixel、Galaxy 和桌面浏览器，并可准确模拟视口、用户代理、触摸事件和设备像素比。

📚 查看设备快速参考 | 提示词指南

截图

文档 | API 参考

安装

你可以使用 npm、mcp-get 或 Smithery 安装此软件包：

使用 npm：

npm install -g @executeautomation/playwright-mcp-server

使用 mcp-get：

npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server

使用 Smithery

通过 Smithery 自动为 Claude Desktop 安装 Playwright MCP：

npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude

使用 Claude Code：

claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server

在 VS Code 中安装

使用以下任一按钮在 VS Code 中安装 Playwright MCP 服务：

或者，你也可以使用 VS Code CLI 安装 Playwright MCP 服务：

# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}'

# For VS Code Insiders
code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}'

安装完成后，即可在 VS Code 中将 ExecuteAutomation Playwright MCP 服务与 GitHub Copilot Agent 配合使用。

浏览器安装

自动安装（推荐）

首次使用 Playwright MCP Server 时，它会自动安装浏览器二进制文件。当服务检测到缺少浏览器时，会：

1. 自动下载并安装所需的浏览器（Chromium、Firefox 或 WebKit）
2. 在控制台中显示安装进度
3. 安装完成后重试你的请求

无需手动设置！ 只需开始使用该服务，它会为你处理浏览器安装。

手动安装（可选）

如果你更倾向于手动安装浏览器，或遇到自动安装问题：

# Install all browsers
npx playwright install

# Or install specific browsers
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

浏览器存储位置

浏览器安装在以下位置：

• Windows： %USERPROFILE%\AppData\Local\ms-playwright
• macOS： ~/Library/Caches/ms-playwright
• Linux： ~/.cache/ms-playwright

配置以使用 Playwright Server

标准模式（stdio）

这是 Claude Desktop 推荐的模式。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

注意： 在 stdio 模式下，日志会自动仅写入文件（而非控制台），以保持 JSON-RPC 通信整洁。日志写入 ~/playwright-mcp-server.log。

HTTP 模式（独立服务）

在没有显示器的系统上运行有头浏览器，或从 IDE 的工作进程运行时，可以将 MCP 服务作为独立 HTTP 服务运行：

Claude Desktop 用户请注意： Claude Desktop 目前要求使用 stdio 模式（command/args 配置）。VS Code、自定义客户端和远程部署推荐使用 HTTP 模式。详情请参阅 CLAUDE_DESKTOP_CONFIG.md。

启动 HTTP 服务

# Using npx
npx @executeautomation/playwright-mcp-server --port 8931

# Or after global installation
playwright-mcp-server --port 8931

服务启动后会显示可用的端点：

==============================================
Playwright MCP Server (HTTP Mode)
==============================================
Port: 8931

ENDPOINTS:
- SSE Stream:     GET  http://localhost:8931/sse
- Messages:       POST http://localhost:8931/messages?sessionId=<id>
- MCP (unified):  GET  http://localhost:8931/mcp
- MCP (unified):  POST http://localhost:8931/mcp?sessionId=<id>
- Health Check:   GET  http://localhost:8931/health
==============================================

HTTP 模式的客户端配置

⚠️ 重要： HTTP/SSE 传输必须包含 "type": "http" 字段！

适用于 VS Code GitHub Copilot：

{
  "github.copilot.chat.mcp.servers": {
    "playwright": {
      "url": "http://localhost:8931/mcp",
      "type": "http"
    }
  }
}

适用于自定义 MCP 客户端：

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp",
      "type": "http"
    }
  }
}

重要： 如果没有 "type": "http"，连接将会失败。

适用于 Claude Desktop： 请改用 stdio 模式（见上文的“标准模式”）

HTTP 模式的使用场景

• 在没有显示器的系统上运行有头浏览器（例如远程服务）
• 与 VS Code GitHub Copilot 集成
• 将服务作为后台服务运行
• 从多个客户端访问服务
• 使用 /health 端点进行调试
• 自定义 MCP 客户端集成

监控： 服务包含一个监控系统，该系统会在动态分配的端口上启动（以避免冲突）。请查看控制台输出，确认实际端口。

注意： 对于 Claude Desktop，目前请继续使用 stdio 模式（见上文的“标准模式”）。

故障排除

“No transport found for sessionId”错误

症状： 出现错误信息为“Bad Request: No transport found for sessionId”的 400 错误

解决方案：

1. 检查配置是否包含 "type": "http"

   {
     "url": "http://localhost:8931/mcp",
     "type": "http"  // ← This is REQUIRED!
   }
   

2. 确认服务日志显示已建立连接：

   # Should see these in order:
   # 1. "Incoming request" - GET /mcp
   # 2. "Transport registered" - with sessionId
   # 3. "POST message received" - with same sessionId
   

3. 重启服务和客户端

连接问题

• 服务无法启动： 检查端口 8931 是否可用
• 外部访问被阻止： 这是出于安全考虑而设计的。服务仅绑定到 localhost
• 远程访问： 使用 SSH 隧道：

  ssh -L 8931:localhost:8931 user@remote-server
  

测试

本项目使用 Jest 进行测试。测试位于 src/__tests__ 目录中。

运行测试

你可以使用以下任一命令运行测试：

# Run tests using the custom script (with coverage)
node run-tests.cjs

# Run tests using npm scripts
npm test           # Run tests without coverage
npm run test:coverage  # Run tests with coverage
npm run test:custom    # Run tests with custom script (same as node run-tests.cjs)

测试覆盖率报告将在 coverage 目录中生成。

运行 evals

evals 包会加载一个 MCP 客户端，然后运行 index.ts 文件，因此无需在测试之间重新构建。你可以在 npx 命令前添加环境变量来加载它们。完整文档请见此处。

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/tools/codegen/index.ts

参与贡献

添加新工具时，请注意工具名称的长度。某些客户端（如 Cursor）对服务名称和工具名称的组合（server_name:tool_name）限制为 60 个字符。

我们的服务名称是 playwright-mcp。请确保工具名称足够短，不会超过此限制。

Star 历史