1. 项目概述当AI代码编辑器遇上浏览器自动化最近在折腾一个挺有意思的组合用 Cursor 编辑器通过 MCP 协议来驱动 Playwright 做 Web 自动化测试。这听起来可能有点绕但简单来说就是让你能在写代码的同一个环境里直接“命令”一个浏览器去干活比如自动登录、抓取数据、截图或者跑测试用例。对于经常需要和网页打交道的开发者或者测试同学来说这相当于把“思考”写代码和“执行”操作浏览器两个环节无缝衔接起来了效率提升不是一点半点。我之所以花时间研究这个是因为传统的自动化测试流程通常比较割裂你在 IDE 里写 Playwright 脚本然后切换到终端去运行再切回来看结果。如果脚本报错了你又得切回去改代码。这个过程来回切换很容易打断思路。而 Cursor 本身就是一个深度集成了 AI 辅助编程的编辑器如果再能把浏览器自动化能力直接“内嵌”进来让它成为 AI 可以调用的一个“工具”那想象力就大了。AI 可以根据你的自然语言描述直接生成并执行操作浏览器的代码甚至实时调试这无疑为快速原型验证、探索性测试或者日常的重复性网页操作提供了全新的可能性。这个环境搭建的核心就三样东西Cursor我们的主战场和AI伙伴、Playwright强大的浏览器自动化库、以及将它们连接起来的MCP协议。接下来我会带你一步步走通整个搭建过程并把我在 Windows 系统下踩过的坑、总结的技巧毫无保留地分享出来目标是让你也能快速拥有这个“网页操控台”。2. 环境搭建全流程与核心原理拆解搭建这个环境本质上是在配置一个客户端-服务器架构。Cursor 作为客户端Playwright MCP 作为服务器它们通过 MCP 协议进行通信。我们的工作就是安装好双方并确保它们能“握手”成功。2.1 基础环境准备Node.js 与 npm一切的基础是 Node.js 运行环境因为 Playwright 和 MCP Server 都是基于 Node.js 的。为什么是 Node.jsPlaywright 虽然支持多种语言Python, .NET, Java但其官方提供的 MCP 服务器实现playwright/mcp是用 JavaScript/Node.js 编写的。MCP 协议本身是进程间通信这里选择用 Node.js 来启动这个服务进程最为直接和官方。版本选择与安装要点我强烈推荐使用 Node.js 的LTS长期支持版本比如 v18.x 或 v20.x。避免使用 v16 或更旧的版本因为一些新的 npm 包或 Playwright 特性可能依赖更新的运行时。官网下载直接访问 Node.js 官网下载对应你操作系统的安装包。Windows 用户就下.msi安装程序。安装验证安装完成后打开命令行CMD 或 PowerShell输入以下命令检查是否成功node -v npm -v如果分别输出了类似v18.18.0和9.8.1的版本号说明安装成功。注意安装 Node.js 时安装程序通常会询问是否将 npm 添加到系统 PATH 环境变量务必勾选此项。这是后续能全局使用npx、npm命令的关键。2.2 核心组件安装Playwright 与 MCP 服务器基础环境就绪后我们来安装两个核心包。全局安装 Playwright MCP 服务器 在命令行中执行npm install -g playwright/mcp-g参数代表全局安装这样你可以在系统的任何位置启动这个 MCP 服务。安装完成后可以用npx playwright/mcp --version来验证是否安装成功它会输出 MCP 服务器的版本号。安装 Playwright 浏览器内核 接着运行 Playwright 的安装命令来下载它需要操作的浏览器Chromium, Firefox, WebKitnpx playwright install这个过程会下载几百兆的浏览器二进制文件请保持网络通畅。如果你想同时安装这些浏览器的系统依赖主要在 Linux 上需要可以运行npx playwright install --with-deps。这里有个关键理解playwright/mcp是一个服务端程序它暴露了一套标准的 MCP 接口。而playwright这个 npm 包是客户端库你的自动化脚本需要require或import它来编写具体的浏览器操作逻辑。MCP 服务在后台管理浏览器实例并执行客户端脚本发来的指令。2.3 Cursor 编辑器的安装与配置Cursor 的安装比较简单去其官网下载安装包按步骤安装即可。安装后需要注册登录这里可能会遇到第一个小坑注册时验证码问题。如果收不到邮件或验证失败可以尝试清理浏览器 Cookie 或更换浏览器重试通常能解决。安装并登录 Cursor 后我们需要配置它去连接我们刚刚安装的 Playwright MCP 服务器。打开 Cursor进入Settings设置。在设置中搜索或找到MCP选项。点击Add MCP server configuration添加 MCP 服务器配置。这会打开一个 JSON 配置文件我们需要在其中添加 Playwright 服务器的定义。最初始、理想的配置看起来是这样的{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest] } } }这个配置告诉 Cursor“当你需要调用 Playwright 功能时去执行npx playwright/mcplatest这个命令来启动服务器。”2.4 Windows 系统下的关键踩坑与解决如果你在 macOS 或 Linux 上上述配置可能直接就成功了。但在 Windows 上我遇到了两个典型问题这也是很多教程里没细说的部分。坑一npx 命令找不到或路径错误保存配置后重启 Cursor它可能会提示无法启动 MCP 服务器或者干脆没反应。这是因为 Cursor 在调用npx时可能找不到正确的路径。根本原因npx是 npm 附带的一个工具用于执行本地或全局的 npm 包。在 Windows 上它的可执行文件通常位于C:\Users\你的用户名\AppData\Roaming\npm目录下。如果这个目录没有在系统的 PATH 环境变量中或者顺序不对Cursor 就找不到它。解决方案手动将 npm 全局包目录添加到系统 PATH并确保其优先级高于其他可能冲突的路径。右键点击“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”或“用户变量”中找到Path变量点击“编辑”。点击“新建”然后输入你的 npm 全局路径例如C:\Users\你的用户名\AppData\Roaming\npm。关键一步使用“上移”按钮将这个新建的条目移动到列表的顶部。这能确保系统优先从这个目录查找命令。点击“确定”保存所有更改。需要重启 Cursor 甚至重启电脑才能使新的 PATH 生效。坑二Cursor 无法正确捕获 npx 进程状态即使路径对了Cursor 在 Windows 上直接调用npx可能也无法正常建立连接和通信。表现为配置了但 Cursor 的 MCP 工具列表里没有出现playwright或者出现后很快断开。根本原因Cursor 需要稳定地启动并管理一个子进程即 MCP 服务器。在 Windows 上直接调用npx可能无法为 Cursor 提供稳定的进程句柄来进行生命周期管理。解决方案通过cmd /c命令来包装npx的调用。cmd /c会启动一个新的 Windows 命令提示符窗口来执行后续命令这个窗口进程可以被 Cursor 更好地管理和附着。 将之前的 Cursor MCP 配置修改为{ mcpServers: { playwright: { command: cmd, args: [/c, npx, playwright/mcplatest] } } }这个配置的意思是执行cmd命令并传递参数/c npx playwright/mcplatest。/c参数告诉cmd执行后面的字符串作为命令然后终止。修改后的效果保存配置并重启 Cursor 后你会看到一个新的命令行窗口弹出。不要关闭它这个窗口就是 Playwright MCP 服务器在运行。稍等片刻回到 Cursor检查工具面板通常侧边栏有个工具图标你应该能看到playwright作为一个可用的工具出现并且旁边有一个绿色的圆点表示连接成功。重要提示这个弹出的命令行窗口必须保持打开状态它是 MCP 服务器进程。关闭它Cursor 就失去了与 Playwright 的连接。你可以将其最小化但不要关闭。3. 第一个自动化脚本从编写到运行环境配好了我们来点实际的写一个简单的脚本验证整个链路是否跑通。3.1 脚本编写与核心 API 解析在 Cursor 里新建一个 JavaScript 文件比如叫test-baidu.js。输入以下内容const { chromium } require(playwright); (async () { // 1. 启动浏览器 const browser await chromium.launch({ headless: false }); // headless: false 表示显示浏览器窗口 const page await browser.newPage(); // 2. 导航到目标页面 await page.goto(https://www.baidu.com); console.log(已成功打开百度首页); // 3. 进行一些简单操作例如获取页面标题 const title await page.title(); console.log(页面标题是:, title); // 4. 模拟用户输入和点击示例搜索“Playwright” await page.fill(input[namewd], Playwright 自动化测试); await page.click(input[typesubmit]); // 等待导航完成 await page.waitForLoadState(networkidle); console.log(搜索完成当前URL:, page.url()); // 5. 等待一段时间以便观察然后关闭浏览器 await page.waitForTimeout(5000); // 等待5秒 await browser.close(); })();代码逐行解析const { chromium } require(playwright);从 Playwright 库中导入chromium对象。Playwright 也支持firefox和webkit。chromium.launch({ headless: false })启动一个 Chromium 浏览器实例。headless: false参数至关重要它让浏览器以有界面的模式运行这样你就能亲眼看到自动化过程。调试时一定要用这个模式默认是true无头模式。browser.newPage()创建一个新的浏览器页面标签页。page.goto(url)让页面导航到指定的 URL。page.title()获取当前页面的标题。page.fill(selector, text)向匹配选择器的输入框填充文本。这里input[name”wd”]是百度首页搜索框的 CSS 选择器。page.click(selector)点击匹配选择器的元素。input[type”submit”]是百度首页的“百度一下”按钮。page.waitForLoadState(‘networkidle’)等待页面网络活动基本停止通常表示页面加载完成。page.waitForTimeout(ms)让脚本暂停指定的毫秒数。在自动化中应优先使用page.waitForSelector或page.waitForFunction等条件等待而非固定等待这里仅为演示。browser.close()关闭浏览器释放资源。3.2 脚本运行与权限问题排查脚本写好了怎么运行呢这里有一个非常重要的概念区分MCP 服务器和你的自动化脚本是两回事。MCP 服务器(playwright/mcp)是一个常驻进程负责接收 Cursor或其它 MCP 客户端的指令并管理浏览器生命周期。我们之前配置并启动的就是它。你的自动化脚本(test-baidu.js)是一个普通的 Node.js 脚本它使用playwright这个库来编写具体的浏览器操作逻辑。因此运行脚本的正确方式是在终端里用 Node.js 直接执行它。而不是通过 MCP 服务器的命令来运行。打开你的终端CMD PowerShell或 Cursor 内置的终端导航到你的脚本所在目录。cd D:\你的项目路径运行脚本node test-baidu.js运行中可能遇到的坑坑一PowerShell 执行策略限制如果你使用 PowerShell首次运行node命令执行脚本时可能会遇到错误提示说脚本执行被禁止。这是因为 PowerShell 默认的执行策略Execution Policy是受限的。解决方案以管理员身份打开 PowerShell执行以下命令修改执行策略Set-ExecutionPolicy RemoteSigned执行后会询问你是否更改输入Y并回车。这个策略允许运行本地创建的脚本以及从互联网下载的已签名脚本对于日常开发是安全的。修改后关闭并重新打开终端即可。坑二模块找不到错误 (Cannot find module ‘playwright’)运行node test-baidu.js时可能会报错Error: Cannot find module ‘playwright’。根本原因playwright这个 npm 包没有被安装在你当前的项目目录下。虽然我们之前用npx playwright install下载了浏览器但那是给全局的 Playwright CLI 用的。你的脚本在本地运行时需要本地的node_modules里有playwright这个库。解决方案在你的项目目录下初始化 npm 并安装 playwright。# 确保你在脚本所在的目录 npm init -y # 快速创建 package.json 文件 npm install playwright # 将 playwright 库安装到当前项目的 node_modules安装完成后再运行node test-baidu.js就应该成功了。你会看到一个 Chromium 浏览器窗口自动打开访问百度输入文字点击搜索然后等待5秒后关闭。实操心得建议为每个自动化测试项目单独创建一个目录并在其中执行npm init和npm install playwright。这样能更好地管理依赖避免全局污染和版本冲突。你可以把playwright/mcp视为一个“基础设施服务”而每个具体的自动化项目则是独立的“客户端应用”。4. 深入 MCP 集成在 Cursor 中直接驱动浏览器前面的步骤验证了 Playwright 脚本可以独立运行。但我们的终极目标是在 Cursor 里更紧密地集成甚至利用 AI 来辅助生成和执行这些自动化操作。这就需要理解 Cursor 的 MCP 工具是如何工作的。4.1 理解 Cursor 中的 MCP 工具当 Playwright MCP 服务器成功连接后它会在 Cursor 中注册一系列“工具”。这些工具本质上是一组可以被 Cursor 的 AI 模型比如 Claude调用的函数。你可以通过 Cursor 的聊天界面或编辑器内的 AI 指令来使用它们。常见的 Playwright MCP 工具可能包括open_browser: 打开一个浏览器。goto_page: 导航到某个 URL。take_screenshot: 对页面截图。get_page_content: 获取页面文本或 HTML。click_element: 点击某个元素。fill_form: 填写表单。如何使用确保 MCP 服务器运行那个命令行窗口开着。在 Cursor 中你可以直接对 AI 说“用 Playwright 打开浏览器访问 GitHub并截图。”Cursor 的 AI 会理解你的意图在后台调用相应的 MCP 工具并可能生成一段临时的 Playwright 脚本代码来执行。这种方式极大地降低了编写自动化脚本的门槛特别适合快速验证一个想法或者执行一些临性的、探索性的网页操作。4.2 高级配置与自定义 MCP 参数基础的 MCP 配置可能不能满足所有需求。Playwright MCP 服务器支持一些启动参数我们可以通过修改 Cursor 的配置来传递这些参数。例如你可能想指定浏览器的启动路径或者使用一个已有的用户数据目录以保持登录状态。你可以这样修改 Cursor 的 MCP 配置{ mcpServers: { playwright: { command: cmd, args: [ /c, npx, playwright/mcplatest, --browser, chromium, --launch-args, --start-maximized --user-data-dirC:\\path\\to\\your\\profile ] } } }参数解释--browser chromium: 指定默认使用 Chromium 浏览器也可是firefox,webkit。--launch-args这个参数后面跟的字符串会直接传递给browser.launch()方法。这里示例中使用了--start-maximized启动时最大化窗口和--user-data-dir指定用户数据目录可以保存 Cookies、缓存等。注意修改 MCP 配置后必须重启 Cursor才能使更改生效。同时你需要关闭之前弹出的 MCP 服务器命令行窗口Cursor 重启时会根据新配置重新启动它。4.3 结合 AI 进行自动化脚本开发这才是 Cursor Playwright MCP 的威力所在。你不再需要从头记忆所有 Playwright 的 API。场景示例你想自动化一个登录流程。在 Cursor 编辑器中打开一个 JS 文件。你可以用自然语言描述需求例如在聊天框里输入“帮我写一段 Playwright 脚本打开浏览器访问 example.com找到 id 是 ‘username’ 和 ‘password’ 的输入框分别填入 ‘myuser’ 和 ‘mypass’然后点击 text 是 ‘Login’ 的按钮。”Cursor 的 AI 会根据你的描述结合它已连接的 Playwright MCP 工具它知道可用的操作生成一段可执行的代码。它甚至可能会建议你先运行一下看看效果。你可以直接运行 AI 生成的这段代码。如果运行出错比如元素选择器不对你可以把错误信息反馈给 AI让它修正代码。这个过程形成了一个“描述-生成-执行-调试”的快速闭环对于编写自动化测试用例或者一次性自动化任务来说效率提升是革命性的。5. 常见问题排查与性能优化指南即使按照步骤操作也难免会遇到问题。这里我总结了一份常见问题排查清单和优化建议。5.1 连接与启动问题排查表问题现象可能原因排查步骤与解决方案Cursor 中看不到playwright工具1. MCP 服务器未启动。2. 配置错误。3. 环境变量问题。1. 检查是否有一个命令行窗口弹出并保持运行。2. 检查 Cursor 的 MCP 配置 JSON 格式是否正确特别是command和args。3. 重启 Cursor。4. 检查系统 PATH 是否包含 npm 路径并尝试用cmd /c包装命令。MCP 服务器窗口一闪而过1.npx命令执行失败。2.playwright/mcp包未全局安装。3. Node.js 版本不兼容。1. 手动在终端运行npx playwright/mcplatest看具体报错信息。2. 运行npm list -g playwright/mcp检查是否已安装。3. 确保 Node.js 版本在 v14 以上推荐 LTS 版本。运行脚本时报Cannot find module ‘playwright’项目本地未安装playwrightnpm 包。在脚本所在目录执行npm install playwright。AI 无法调用 Playwright 工具或调用失败1. MCP 连接不稳定。2. AI 模型不理解上下文。3. 工具调用超时。1. 确认 MCP 服务器绿色圆点常亮。2. 在聊天中明确提示 AI “使用 Playwright 工具”。3. 检查网络复杂的操作可能需要更长的超时时间。浏览器无法启动或启动报错1. Playwright 浏览器未安装完整。2. 系统缺少浏览器依赖Linux常见。3. 杀毒软件或防火墙拦截。1. 重新运行npx playwright install。2. 对于 Linux运行npx playwright install-deps。3. 暂时禁用杀毒软件或防火墙或将 Playwright 相关进程加入白名单。5.2 稳定性与性能优化建议使用项目级依赖对于正式的自动化项目永远在项目目录下使用npm install playwright而不是依赖全局。这能保证团队协作和部署时环境一致。可以将playwright/mcp视为一个独立的“服务”而项目代码是它的“客户端”。管理浏览器上下文Playwright 的browser.newContext()可以创建一个独立的浏览器上下文类似于一个独立的隐身会话这比直接创建页面 (browser.newPage()) 更轻量且能实现更好的隔离Cookies、缓存独立。对于需要并行执行多个独立场景的测试使用上下文Context是更佳实践。避免固定等待多用智能等待page.waitForTimeout(5000)这种固定等待是脆弱的网络或机器性能变化会导致等待时间不足或过长。优先使用page.waitForSelector(‘#elementId’)等待某个元素出现。page.waitForLoadState(‘networkidle’)等待网络空闲。page.waitForFunction()等待某个 JavaScript 条件成立。 这能让你的脚本更健壮、运行更快。复用浏览器实例如果你的自动化任务是一系列连续的操作尽量复用同一个browser实例而不是每个任务都启动关闭一次浏览器。启动浏览器的开销是很大的。MCP 服务器本身会管理浏览器实例但你的脚本逻辑也应注意这一点。妥善处理 MCP 服务器窗口那个弹出的命令行窗口是服务器的生命线。你可以将其最小化到任务栏。如果意外关闭了需要去 Cursor 的设置里暂时禁用再启用 MCP 配置或者重启 Cursor 来重新启动它。探索 Cursor 的 AI 指令模式除了聊天Cursor 的编辑器内 AI 指令通常按Cmd/CtrlK触发也非常强大。你可以选中一段描述性文字用指令让它“转换为 Playwright 脚本”或者对一段有问题的脚本说“调试这段 Playwright 代码”。充分利用 AI 能极大提升开发体验。搭建并熟练使用 Cursor Playwright MCP 这套环境相当于为你配备了一个随时待命的网页操作机器人并且这个机器人还能听懂你的自然语言指令。它特别适合前端开发者自测、测试工程师快速编写用例、运营或数据分析人员执行一些规律的网页数据抓取任务。一开始的配置过程可能会遇到一些系统环境相关的小麻烦但一旦打通你会发现它为网页自动化工作流带来的流畅感和可能性绝对是值得投入的。
1. 项目概述当AI代码编辑器遇上浏览器自动化最近在折腾一个挺有意思的组合用 Cursor 编辑器通过 MCP 协议来驱动 Playwright 做 Web 自动化测试。这听起来可能有点绕但简单来说就是让你能在写代码的同一个环境里直接“命令”一个浏览器去干活比如自动登录、抓取数据、截图或者跑测试用例。对于经常需要和网页打交道的开发者或者测试同学来说这相当于把“思考”写代码和“执行”操作浏览器两个环节无缝衔接起来了效率提升不是一点半点。我之所以花时间研究这个是因为传统的自动化测试流程通常比较割裂你在 IDE 里写 Playwright 脚本然后切换到终端去运行再切回来看结果。如果脚本报错了你又得切回去改代码。这个过程来回切换很容易打断思路。而 Cursor 本身就是一个深度集成了 AI 辅助编程的编辑器如果再能把浏览器自动化能力直接“内嵌”进来让它成为 AI 可以调用的一个“工具”那想象力就大了。AI 可以根据你的自然语言描述直接生成并执行操作浏览器的代码甚至实时调试这无疑为快速原型验证、探索性测试或者日常的重复性网页操作提供了全新的可能性。这个环境搭建的核心就三样东西Cursor我们的主战场和AI伙伴、Playwright强大的浏览器自动化库、以及将它们连接起来的MCP协议。接下来我会带你一步步走通整个搭建过程并把我在 Windows 系统下踩过的坑、总结的技巧毫无保留地分享出来目标是让你也能快速拥有这个“网页操控台”。2. 环境搭建全流程与核心原理拆解搭建这个环境本质上是在配置一个客户端-服务器架构。Cursor 作为客户端Playwright MCP 作为服务器它们通过 MCP 协议进行通信。我们的工作就是安装好双方并确保它们能“握手”成功。2.1 基础环境准备Node.js 与 npm一切的基础是 Node.js 运行环境因为 Playwright 和 MCP Server 都是基于 Node.js 的。为什么是 Node.jsPlaywright 虽然支持多种语言Python, .NET, Java但其官方提供的 MCP 服务器实现playwright/mcp是用 JavaScript/Node.js 编写的。MCP 协议本身是进程间通信这里选择用 Node.js 来启动这个服务进程最为直接和官方。版本选择与安装要点我强烈推荐使用 Node.js 的LTS长期支持版本比如 v18.x 或 v20.x。避免使用 v16 或更旧的版本因为一些新的 npm 包或 Playwright 特性可能依赖更新的运行时。官网下载直接访问 Node.js 官网下载对应你操作系统的安装包。Windows 用户就下.msi安装程序。安装验证安装完成后打开命令行CMD 或 PowerShell输入以下命令检查是否成功node -v npm -v如果分别输出了类似v18.18.0和9.8.1的版本号说明安装成功。注意安装 Node.js 时安装程序通常会询问是否将 npm 添加到系统 PATH 环境变量务必勾选此项。这是后续能全局使用npx、npm命令的关键。2.2 核心组件安装Playwright 与 MCP 服务器基础环境就绪后我们来安装两个核心包。全局安装 Playwright MCP 服务器 在命令行中执行npm install -g playwright/mcp-g参数代表全局安装这样你可以在系统的任何位置启动这个 MCP 服务。安装完成后可以用npx playwright/mcp --version来验证是否安装成功它会输出 MCP 服务器的版本号。安装 Playwright 浏览器内核 接着运行 Playwright 的安装命令来下载它需要操作的浏览器Chromium, Firefox, WebKitnpx playwright install这个过程会下载几百兆的浏览器二进制文件请保持网络通畅。如果你想同时安装这些浏览器的系统依赖主要在 Linux 上需要可以运行npx playwright install --with-deps。这里有个关键理解playwright/mcp是一个服务端程序它暴露了一套标准的 MCP 接口。而playwright这个 npm 包是客户端库你的自动化脚本需要require或import它来编写具体的浏览器操作逻辑。MCP 服务在后台管理浏览器实例并执行客户端脚本发来的指令。2.3 Cursor 编辑器的安装与配置Cursor 的安装比较简单去其官网下载安装包按步骤安装即可。安装后需要注册登录这里可能会遇到第一个小坑注册时验证码问题。如果收不到邮件或验证失败可以尝试清理浏览器 Cookie 或更换浏览器重试通常能解决。安装并登录 Cursor 后我们需要配置它去连接我们刚刚安装的 Playwright MCP 服务器。打开 Cursor进入Settings设置。在设置中搜索或找到MCP选项。点击Add MCP server configuration添加 MCP 服务器配置。这会打开一个 JSON 配置文件我们需要在其中添加 Playwright 服务器的定义。最初始、理想的配置看起来是这样的{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest] } } }这个配置告诉 Cursor“当你需要调用 Playwright 功能时去执行npx playwright/mcplatest这个命令来启动服务器。”2.4 Windows 系统下的关键踩坑与解决如果你在 macOS 或 Linux 上上述配置可能直接就成功了。但在 Windows 上我遇到了两个典型问题这也是很多教程里没细说的部分。坑一npx 命令找不到或路径错误保存配置后重启 Cursor它可能会提示无法启动 MCP 服务器或者干脆没反应。这是因为 Cursor 在调用npx时可能找不到正确的路径。根本原因npx是 npm 附带的一个工具用于执行本地或全局的 npm 包。在 Windows 上它的可执行文件通常位于C:\Users\你的用户名\AppData\Roaming\npm目录下。如果这个目录没有在系统的 PATH 环境变量中或者顺序不对Cursor 就找不到它。解决方案手动将 npm 全局包目录添加到系统 PATH并确保其优先级高于其他可能冲突的路径。右键点击“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”或“用户变量”中找到Path变量点击“编辑”。点击“新建”然后输入你的 npm 全局路径例如C:\Users\你的用户名\AppData\Roaming\npm。关键一步使用“上移”按钮将这个新建的条目移动到列表的顶部。这能确保系统优先从这个目录查找命令。点击“确定”保存所有更改。需要重启 Cursor 甚至重启电脑才能使新的 PATH 生效。坑二Cursor 无法正确捕获 npx 进程状态即使路径对了Cursor 在 Windows 上直接调用npx可能也无法正常建立连接和通信。表现为配置了但 Cursor 的 MCP 工具列表里没有出现playwright或者出现后很快断开。根本原因Cursor 需要稳定地启动并管理一个子进程即 MCP 服务器。在 Windows 上直接调用npx可能无法为 Cursor 提供稳定的进程句柄来进行生命周期管理。解决方案通过cmd /c命令来包装npx的调用。cmd /c会启动一个新的 Windows 命令提示符窗口来执行后续命令这个窗口进程可以被 Cursor 更好地管理和附着。 将之前的 Cursor MCP 配置修改为{ mcpServers: { playwright: { command: cmd, args: [/c, npx, playwright/mcplatest] } } }这个配置的意思是执行cmd命令并传递参数/c npx playwright/mcplatest。/c参数告诉cmd执行后面的字符串作为命令然后终止。修改后的效果保存配置并重启 Cursor 后你会看到一个新的命令行窗口弹出。不要关闭它这个窗口就是 Playwright MCP 服务器在运行。稍等片刻回到 Cursor检查工具面板通常侧边栏有个工具图标你应该能看到playwright作为一个可用的工具出现并且旁边有一个绿色的圆点表示连接成功。重要提示这个弹出的命令行窗口必须保持打开状态它是 MCP 服务器进程。关闭它Cursor 就失去了与 Playwright 的连接。你可以将其最小化但不要关闭。3. 第一个自动化脚本从编写到运行环境配好了我们来点实际的写一个简单的脚本验证整个链路是否跑通。3.1 脚本编写与核心 API 解析在 Cursor 里新建一个 JavaScript 文件比如叫test-baidu.js。输入以下内容const { chromium } require(playwright); (async () { // 1. 启动浏览器 const browser await chromium.launch({ headless: false }); // headless: false 表示显示浏览器窗口 const page await browser.newPage(); // 2. 导航到目标页面 await page.goto(https://www.baidu.com); console.log(已成功打开百度首页); // 3. 进行一些简单操作例如获取页面标题 const title await page.title(); console.log(页面标题是:, title); // 4. 模拟用户输入和点击示例搜索“Playwright” await page.fill(input[namewd], Playwright 自动化测试); await page.click(input[typesubmit]); // 等待导航完成 await page.waitForLoadState(networkidle); console.log(搜索完成当前URL:, page.url()); // 5. 等待一段时间以便观察然后关闭浏览器 await page.waitForTimeout(5000); // 等待5秒 await browser.close(); })();代码逐行解析const { chromium } require(playwright);从 Playwright 库中导入chromium对象。Playwright 也支持firefox和webkit。chromium.launch({ headless: false })启动一个 Chromium 浏览器实例。headless: false参数至关重要它让浏览器以有界面的模式运行这样你就能亲眼看到自动化过程。调试时一定要用这个模式默认是true无头模式。browser.newPage()创建一个新的浏览器页面标签页。page.goto(url)让页面导航到指定的 URL。page.title()获取当前页面的标题。page.fill(selector, text)向匹配选择器的输入框填充文本。这里input[name”wd”]是百度首页搜索框的 CSS 选择器。page.click(selector)点击匹配选择器的元素。input[type”submit”]是百度首页的“百度一下”按钮。page.waitForLoadState(‘networkidle’)等待页面网络活动基本停止通常表示页面加载完成。page.waitForTimeout(ms)让脚本暂停指定的毫秒数。在自动化中应优先使用page.waitForSelector或page.waitForFunction等条件等待而非固定等待这里仅为演示。browser.close()关闭浏览器释放资源。3.2 脚本运行与权限问题排查脚本写好了怎么运行呢这里有一个非常重要的概念区分MCP 服务器和你的自动化脚本是两回事。MCP 服务器(playwright/mcp)是一个常驻进程负责接收 Cursor或其它 MCP 客户端的指令并管理浏览器生命周期。我们之前配置并启动的就是它。你的自动化脚本(test-baidu.js)是一个普通的 Node.js 脚本它使用playwright这个库来编写具体的浏览器操作逻辑。因此运行脚本的正确方式是在终端里用 Node.js 直接执行它。而不是通过 MCP 服务器的命令来运行。打开你的终端CMD PowerShell或 Cursor 内置的终端导航到你的脚本所在目录。cd D:\你的项目路径运行脚本node test-baidu.js运行中可能遇到的坑坑一PowerShell 执行策略限制如果你使用 PowerShell首次运行node命令执行脚本时可能会遇到错误提示说脚本执行被禁止。这是因为 PowerShell 默认的执行策略Execution Policy是受限的。解决方案以管理员身份打开 PowerShell执行以下命令修改执行策略Set-ExecutionPolicy RemoteSigned执行后会询问你是否更改输入Y并回车。这个策略允许运行本地创建的脚本以及从互联网下载的已签名脚本对于日常开发是安全的。修改后关闭并重新打开终端即可。坑二模块找不到错误 (Cannot find module ‘playwright’)运行node test-baidu.js时可能会报错Error: Cannot find module ‘playwright’。根本原因playwright这个 npm 包没有被安装在你当前的项目目录下。虽然我们之前用npx playwright install下载了浏览器但那是给全局的 Playwright CLI 用的。你的脚本在本地运行时需要本地的node_modules里有playwright这个库。解决方案在你的项目目录下初始化 npm 并安装 playwright。# 确保你在脚本所在的目录 npm init -y # 快速创建 package.json 文件 npm install playwright # 将 playwright 库安装到当前项目的 node_modules安装完成后再运行node test-baidu.js就应该成功了。你会看到一个 Chromium 浏览器窗口自动打开访问百度输入文字点击搜索然后等待5秒后关闭。实操心得建议为每个自动化测试项目单独创建一个目录并在其中执行npm init和npm install playwright。这样能更好地管理依赖避免全局污染和版本冲突。你可以把playwright/mcp视为一个“基础设施服务”而每个具体的自动化项目则是独立的“客户端应用”。4. 深入 MCP 集成在 Cursor 中直接驱动浏览器前面的步骤验证了 Playwright 脚本可以独立运行。但我们的终极目标是在 Cursor 里更紧密地集成甚至利用 AI 来辅助生成和执行这些自动化操作。这就需要理解 Cursor 的 MCP 工具是如何工作的。4.1 理解 Cursor 中的 MCP 工具当 Playwright MCP 服务器成功连接后它会在 Cursor 中注册一系列“工具”。这些工具本质上是一组可以被 Cursor 的 AI 模型比如 Claude调用的函数。你可以通过 Cursor 的聊天界面或编辑器内的 AI 指令来使用它们。常见的 Playwright MCP 工具可能包括open_browser: 打开一个浏览器。goto_page: 导航到某个 URL。take_screenshot: 对页面截图。get_page_content: 获取页面文本或 HTML。click_element: 点击某个元素。fill_form: 填写表单。如何使用确保 MCP 服务器运行那个命令行窗口开着。在 Cursor 中你可以直接对 AI 说“用 Playwright 打开浏览器访问 GitHub并截图。”Cursor 的 AI 会理解你的意图在后台调用相应的 MCP 工具并可能生成一段临时的 Playwright 脚本代码来执行。这种方式极大地降低了编写自动化脚本的门槛特别适合快速验证一个想法或者执行一些临性的、探索性的网页操作。4.2 高级配置与自定义 MCP 参数基础的 MCP 配置可能不能满足所有需求。Playwright MCP 服务器支持一些启动参数我们可以通过修改 Cursor 的配置来传递这些参数。例如你可能想指定浏览器的启动路径或者使用一个已有的用户数据目录以保持登录状态。你可以这样修改 Cursor 的 MCP 配置{ mcpServers: { playwright: { command: cmd, args: [ /c, npx, playwright/mcplatest, --browser, chromium, --launch-args, --start-maximized --user-data-dirC:\\path\\to\\your\\profile ] } } }参数解释--browser chromium: 指定默认使用 Chromium 浏览器也可是firefox,webkit。--launch-args这个参数后面跟的字符串会直接传递给browser.launch()方法。这里示例中使用了--start-maximized启动时最大化窗口和--user-data-dir指定用户数据目录可以保存 Cookies、缓存等。注意修改 MCP 配置后必须重启 Cursor才能使更改生效。同时你需要关闭之前弹出的 MCP 服务器命令行窗口Cursor 重启时会根据新配置重新启动它。4.3 结合 AI 进行自动化脚本开发这才是 Cursor Playwright MCP 的威力所在。你不再需要从头记忆所有 Playwright 的 API。场景示例你想自动化一个登录流程。在 Cursor 编辑器中打开一个 JS 文件。你可以用自然语言描述需求例如在聊天框里输入“帮我写一段 Playwright 脚本打开浏览器访问 example.com找到 id 是 ‘username’ 和 ‘password’ 的输入框分别填入 ‘myuser’ 和 ‘mypass’然后点击 text 是 ‘Login’ 的按钮。”Cursor 的 AI 会根据你的描述结合它已连接的 Playwright MCP 工具它知道可用的操作生成一段可执行的代码。它甚至可能会建议你先运行一下看看效果。你可以直接运行 AI 生成的这段代码。如果运行出错比如元素选择器不对你可以把错误信息反馈给 AI让它修正代码。这个过程形成了一个“描述-生成-执行-调试”的快速闭环对于编写自动化测试用例或者一次性自动化任务来说效率提升是革命性的。5. 常见问题排查与性能优化指南即使按照步骤操作也难免会遇到问题。这里我总结了一份常见问题排查清单和优化建议。5.1 连接与启动问题排查表问题现象可能原因排查步骤与解决方案Cursor 中看不到playwright工具1. MCP 服务器未启动。2. 配置错误。3. 环境变量问题。1. 检查是否有一个命令行窗口弹出并保持运行。2. 检查 Cursor 的 MCP 配置 JSON 格式是否正确特别是command和args。3. 重启 Cursor。4. 检查系统 PATH 是否包含 npm 路径并尝试用cmd /c包装命令。MCP 服务器窗口一闪而过1.npx命令执行失败。2.playwright/mcp包未全局安装。3. Node.js 版本不兼容。1. 手动在终端运行npx playwright/mcplatest看具体报错信息。2. 运行npm list -g playwright/mcp检查是否已安装。3. 确保 Node.js 版本在 v14 以上推荐 LTS 版本。运行脚本时报Cannot find module ‘playwright’项目本地未安装playwrightnpm 包。在脚本所在目录执行npm install playwright。AI 无法调用 Playwright 工具或调用失败1. MCP 连接不稳定。2. AI 模型不理解上下文。3. 工具调用超时。1. 确认 MCP 服务器绿色圆点常亮。2. 在聊天中明确提示 AI “使用 Playwright 工具”。3. 检查网络复杂的操作可能需要更长的超时时间。浏览器无法启动或启动报错1. Playwright 浏览器未安装完整。2. 系统缺少浏览器依赖Linux常见。3. 杀毒软件或防火墙拦截。1. 重新运行npx playwright install。2. 对于 Linux运行npx playwright install-deps。3. 暂时禁用杀毒软件或防火墙或将 Playwright 相关进程加入白名单。5.2 稳定性与性能优化建议使用项目级依赖对于正式的自动化项目永远在项目目录下使用npm install playwright而不是依赖全局。这能保证团队协作和部署时环境一致。可以将playwright/mcp视为一个独立的“服务”而项目代码是它的“客户端”。管理浏览器上下文Playwright 的browser.newContext()可以创建一个独立的浏览器上下文类似于一个独立的隐身会话这比直接创建页面 (browser.newPage()) 更轻量且能实现更好的隔离Cookies、缓存独立。对于需要并行执行多个独立场景的测试使用上下文Context是更佳实践。避免固定等待多用智能等待page.waitForTimeout(5000)这种固定等待是脆弱的网络或机器性能变化会导致等待时间不足或过长。优先使用page.waitForSelector(‘#elementId’)等待某个元素出现。page.waitForLoadState(‘networkidle’)等待网络空闲。page.waitForFunction()等待某个 JavaScript 条件成立。 这能让你的脚本更健壮、运行更快。复用浏览器实例如果你的自动化任务是一系列连续的操作尽量复用同一个browser实例而不是每个任务都启动关闭一次浏览器。启动浏览器的开销是很大的。MCP 服务器本身会管理浏览器实例但你的脚本逻辑也应注意这一点。妥善处理 MCP 服务器窗口那个弹出的命令行窗口是服务器的生命线。你可以将其最小化到任务栏。如果意外关闭了需要去 Cursor 的设置里暂时禁用再启用 MCP 配置或者重启 Cursor 来重新启动它。探索 Cursor 的 AI 指令模式除了聊天Cursor 的编辑器内 AI 指令通常按Cmd/CtrlK触发也非常强大。你可以选中一段描述性文字用指令让它“转换为 Playwright 脚本”或者对一段有问题的脚本说“调试这段 Playwright 代码”。充分利用 AI 能极大提升开发体验。搭建并熟练使用 Cursor Playwright MCP 这套环境相当于为你配备了一个随时待命的网页操作机器人并且这个机器人还能听懂你的自然语言指令。它特别适合前端开发者自测、测试工程师快速编写用例、运营或数据分析人员执行一些规律的网页数据抓取任务。一开始的配置过程可能会遇到一些系统环境相关的小麻烦但一旦打通你会发现它为网页自动化工作流带来的流畅感和可能性绝对是值得投入的。
