# @executeautomation/playwright-mcp-server 中文文档 规范地址：https://npmcn.com/package/%40executeautomation/playwright-mcp-server/ 版本：1\.0\.12 npm 元数据更新时间：2025-12-12T08:08:12.294Z 中文译文更新时间：2026-11-14T03:23:03.136Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40executeautomation/playwright-mcp-server 原文对照：https://npmcn.com/package/%40executeautomation/playwright-mcp-server/?lang=original 项目主页：https://executeautomation.github.io/mcp-playwright/ 源码仓库：https://github.com/executeautomation/mcp-playwright ## 关键信息（来自 npm 元数据） - 包体积（解压后）：251 kB，83 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：10 个 - 首次发布：2024-12-05T00:26:22.973Z - 最新版本发布：2025-12-12T08:08:12.010Z - 近 30 天下载量：50297（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：25（近 12 个月 6 个） ## 中文简介 Playwright 的模拟上下文协议服务器 ## 安装 ```sh npm install @executeautomation/playwright-mcp-server ``` 也可以使用：`pnpm add @executeautomation/playwright-mcp-server`、`yarn add @executeautomation/playwright-mcp-server`、`bun add @executeautomation/playwright-mcp-server` ## README
MseeP.ai Security Assessment BadgeWarp sponsorship
MseeP.ai 安全评估特别感谢 扭曲, 开发者的 AI 终端
* * * # Playwright MCP 服务器 QQ [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/executeautomation/mcp-playwright)](https://archestra.ai/mcp-catalog/executeautomation__mcp-playwright) [![smithery badge](https://smithery.ai/badge/@executeautomation/playwright-mcp-server)](https://smithery.ai/server/@executeautomation/playwright-mcp-server) 一个模型背景协议服务器,使用Playwright提供浏览器自动化能力. 这个服务器可以使LLMs与网页交互,取出截图,生成测试代码,网页刮取页面,并在真实的浏览器环境中执行JavaScript. [![mcp-playwright MCP server](https://glama.ai/mcp/servers/yh4lgtwgbe/badge)](https://glama.ai/mcp/servers/yh4lgtwgbe) ## v1.0.10中的新内容 ### XQ设备模拟 143个真实设备预设! 测试您的网络应用程序 **真实设备配置** 带有简单命令: ```javascript // 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" }); ``` **人工智能助理的自然语言支持:** - "iPhone 13测试" - 切换到 iPad 视图 - "转入地貌" **支持143个设备:** iPhone, iPad, Pixel, Galaxy, 和桌面浏览器, 适当模拟了取景口, 用户代理, 触摸事件, 以及设备像素比例 . 📚 [查看设备快速引用](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Device-Quick-Reference) | [提示指南](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Resize-Prompts-Guide) ## 截图 ![Playwright + Claude](https://npmcn.com/package/%40executeautomation/playwright-mcp-server/image/playwright_claude.png) ## [文档](https://executeautomation.github.io/mcp-playwright/) | [API 参考](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Supported-Tools) ## 安装 您可以使用 npm 、 mcp- get 或 Smithery 安装软件包 : 使用 npm : ```bash npm install -g @executeautomation/playwright-mcp-server ``` 使用 mcp- get : ```bash npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server ``` 使用闪烁 为克洛德桌面自动安装 Playwright MCP [史密斯术](https://smithery.ai/server/@executeautomation/playwright-mcp-server)数字 : ```bash npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude ``` 使用 Claude 代码 : ```bash claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server ``` #### 在 VS 代码中安装 在 VS 代码中安装 Playwright MCP 服务器 : [![Install in VS Code](https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540executeautomation%252Fplaywright-mcp-server%2522%255D%257D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540executeautomation%252Fplaywright-mcp-server%2522%255D%257D) 或者,您可以使用 VS 代码 CLI 安装 Playwright MCP 服务器 : ```bash # For VS Code code --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}' ``` ```bash # For VS Code Insiders code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}' ``` 在安装后, Execute Automation Playwright MCP 服务器将可用您的 GitHub 副驾驶代理在 VS 代码中使用 . ## 浏览器安装 ### 自动安装( 建议) Playwright MCP 服务器 **自动安装浏览器二进制** 当你第一次使用它。 当服务器发现浏览器缺失时,它将: 1. 自动下载并安装所需的浏览器( Chromium, Firefox, 或 WebKit) 2. 在控制台中显示安装进度 3. 安装完成后重试您的请求 **不需要手动设置!** 刚刚开始使用服务器,它处理您的浏览器安装. ### 手动安装( 可选) 如果您喜欢手动安装浏览器或遇到任何自动安装的问题: ```bash # Install all browsers npx playwright install # Or install specific browsers npx playwright install chromium npx playwright install firefox npx playwright install webkit ``` ### 浏览器存储位置 浏览器安装到: - **窗口 :** `%USERPROFILE%\AppData\Local\ms-playwright` - **马可斯:** `~/Library/Caches/ms-playwright` - **林纳:** `~/.cache/ms-playwright` ## 要使用 Playwright 服务器的配置 ### 标准模式( stdio) 这是 **claude 桌面推荐模式**。 。 。 . ```json { "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@executeautomation/playwright-mcp-server"] } } } ``` **说明:** 在stdio模式下,日志会自动被引导到只有文件(而不是控制台)来维护干净的JSON-RPC通信. 日志写入 `~/playwright-mcp-server.log`。 。 。 . ### HTTP 模式( 自动服务器) 在不显示或从IDes的工人进程运行系统时,您可以将MCP服务器作为独立的HTTP服务器运行: > **Claude 桌面用户的说明 :** Claude桌面目前需要stdio模式(命令/args配置). 为VS代码,自定义客户端以及远程部署推荐了HTTP模式. 见 [CLUDE DESKTOP CONFig.md (英语)](https://npmcn.com/package/%40executeautomation/playwright-mcp-server/CLAUDE_DESKTOP_CONFIG.md) 详细情况. #### 启动 HTTP 服务器 ```bash # 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= - MCP (unified): GET http://localhost:8931/mcp - MCP (unified): POST http://localhost:8931/mcp?sessionId= - Health Check: GET http://localhost:8931/health ============================================== ``` #### HTTP 模式的客户端配置 > **{\\FN黑体\\FS22\\BORD1\\SHAD0\\3AHBE\\4AH00\\FSCX67\\FSCY66\\2CHFFFFFF\\3CH808080}你觉得呢** 这个 `"type": "http"` 字段为 **需求** hTTP/SSE运输! **VS 代码 GitHub 副驾驶 :** ```json { "github.copilot.chat.mcp.servers": { "playwright": { "url": "http://localhost:8931/mcp", "type": "http" } } } ``` **自定义 MCP 客户 :** ```json { "mcpServers": { "playwright": { "url": "http://localhost:8931/mcp", "type": "http" } } } ``` **重要内容:** 无 `"type": "http"`,连接将失败. **对于克洛德桌面:** 代之以使用 stdio 模式( 见上文标准模式) #### HTTP 模式使用大小写 - 在不显示的系统(如远程服务器)上运行首选项浏览器 - 与 VS 代码 GitHub 合并 - 作为背景服务运行服务器 - 从多个客户端访问服务器 - 与调试 `/health` 结束点 - 自定义 MCP 客户端集成 **监测:** 服务器包括一个从动态分配的端口(避免冲突)开始的监测系统. 检查控制台输出到实际端口 . **说明:** 对于克洛德桌面,现在继续使用stdio模式(上方标准模式). ## 解决问题 ### "没有找到会话的运输工具" Id" 错误 **症状 :** 400 个错误, 有信件“ 坏请求: 找不到会话的传送 爱德" **解决方案 :** 1. **检查配置包含 `"type": "http"`** ```json { "url": "http://localhost:8931/mcp", "type": "http" // ← This is REQUIRED! } ``` 2. **验证服务器日志显示连接 :** ```bash # Should see these in order: # 1. "Incoming request" - GET /mcp # 2. "Transport registered" - with sessionId # 3. "POST message received" - with same sessionId ``` 3. **重新启动服务器和客户端** ### 连接问题 - **服务器未启动 :** 检查是否可用的端口 8931 - **外部访问被屏蔽 :** 这是设计(安全)的。 服务器只绑定到本地主机 - **对于远程访问:** 使用 SSH 隧道 : ```bash ssh -L 8931:localhost:8931 user@remote-server ``` ## 测试 这个项目使用Jest进行测试. 测试地点位于 `src/__tests__` 目录. ### 运行测试 您可以使用下列命令之一进行测试: ```bash # 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客户端,然后运行索引.ts文件,因此在测试之间不需要重建. 您可以通过前缀 npx 命令来加载环境变量 。 完整的文档可以找到 [这里](https://www.mcpevals.io/docs)。 。 。 . ```bash 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 History Chart](https://api.star-history.com/svg?repos=executeautomation/mcp-playwright&type=Date)](https://star-history.com/#executeautomation/mcp-playwright&Date) ## 常见问题 ### @executeautomation/playwright-mcp-server 是什么？ Playwright 的模拟上下文协议服务器 ### 如何安装 @executeautomation/playwright-mcp-server？ 在项目目录运行 npm install @executeautomation/playwright-mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 playwright-mcp-server，可以用 npx playwright-mcp-server 直接运行。 ### @executeautomation/playwright-mcp-server 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @executeautomation/playwright-mcp-server 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @executeautomation/playwright-mcp-server 可以商用吗？ @executeautomation/playwright-mcp-server 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @executeautomation/playwright-mcp-server 的下载量有多少？ 根据 npm 官方下载统计，@executeautomation/playwright-mcp-server 在 2026/10/14 – 2026/11/12 这 30 天内被下载 50,297 次，日均约 1,677 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @executeautomation/playwright-mcp-server 还在维护吗？ 最新版本 1\.0\.12 发布于 2025/12/12（11 个月前）；至今共发布 25 个版本，其中过去 12 个月发布了 6 个；首次发布于 2024/12/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。