Playwright MCP Server 000

一个基于 Model Context Protocol 的服务器，通过 Playwright 提供浏览器自动化能力。它可以让 LLM 与网页交互、截屏截图、生成测试代码、抓取网页内容，并在真实浏览器环境中执行 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 以及桌面浏览器，正确模拟视口、user-agent、触摸事件和设备像素比。

📚 查看设备速查手册 | Prompt 指南

Related MCP server: Cloudflare Playwright MCP

截图

文档 | 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 服务器：

[<<image in VS Code%://Mmm) …](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%25A%2522playwright%2522%252C%2522command%2522%25A%2522npx%2522%252C%2522args%2522%253A%255B%2522-american%2522%252C%2522%2540executeautomation%252Fplaywright-mcp-server%2522%255D%257D) <[img](alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">

或者，您也可以通过 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"]}'

安装完成后，ExecuteAutomation Playwright MCP 服务器即可在 VS Code 中与您的 GitHub Copilot 代理一起使用。

浏览器安装

自动安装（推荐）

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 的 worker 进程中运行有头浏览器时，可以将 MCP 服务器作为独立 HTTP 服务器运行：

Claude Desktop 用户可以： Claude Desktop 目前要求 stdio 模式（command/args 配置）。HTTP 模式建议用于 VS Code、自定义客户端和远程部署。详情见 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"
    }
  }
}

适用于自定义客户端：

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

**重要：**MCP 缺少 "type": "http"，连接将会失败。

对于 Claude Desktop： 请使用 stdio 模式（见上文标准模式）

HTTP 模式使用场景

• 在无显示器的系统上运行有头浏览器（例如远程服务器）

• 与 VS Code GitHub Copilot 集成

• 作为后台服务运行服务器

• 从多个客户端访问服务器

• 使用 /health 端点进行调试

• 自不确定 MCP 客户端集成

监控： 服务器内置监控系统，会自动分配一个动态端口（避免冲突）。请查看控制台输出获取实际端口。

注意： 对于 Claude Desktop，请继续使用标准模式（见上文）。

故障排除

"No transport found for sessionId" 错误

症状： 400 错误，消息为 "Bad Request: No transport found for sessionId"

解决：

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. 重启服务器和客户端

连接问题

• 服务器无法启动： Check if port 8931 is available

• 外部访问被阻止： 这是设计使然（出于安全）。服务器仅绑定 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 命令前加上环境变量前缀。完整文档请见 [more].

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

贡献

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

我们的服务器名称为 playwright-mcp。请保证工具名得足够短，以免超过该限制。

Star 历史