Playwriter：开源AI浏览器自动化MCP工具，无缝衔接LLM与真实浏览器环境

一、Playwriter是什么

Playwriter是一套围绕浏览器自动化与AI协同构建的工具集，核心由Chrome扩展（Playwriter MCP）和本地Node.js中继服务组成，主打通过Chrome DevTools Protocol (CDP) 让Playwright框架直接连接到用户正在使用的Chrome浏览器实例，实现无需单独启动浏览器、无需手动配置CDP模式的轻量化浏览器自动化操作。

作为Model Context Protocol (MCP) 协议的典型落地服务，Playwriter打破了传统Playwright、Selenium等自动化工具的使用局限，将大语言模型（LLM）与真实的浏览器环境无缝衔接，让AI工具能够直接“接管”用户的浏览器标签页，模拟人类完成各类网页操作。与原生Playwright MCP相比，Playwriter在性能、资源占用、隐私性上均做了深度优化，同时保留了完整的Playwright API能力，是面向AI时代的下一代浏览器自动化解决方案。

该项目基于TypeScript开发，采用monorepo架构管理，所有代码开源且遵循Apache-2.0协议，支持自由使用与二次开发，无商业授权限制，目前已成为AI社区中备受关注的浏览器自动化工具之一。

二、功能特色

Playwriter的核心价值在于轻量化、本地化、AI协同化，既解决了传统自动化工具的资源占用高、环境配置复杂、无法复用浏览器状态等痛点，又实现了与MCP协议AI工具的深度融合，其功能特色可分为核心性能优化、核心能力升级、隐私安全保障、灵活使用方式四大类，核心功能点与能力对应如下表所示：

除上述核心功能外，Playwriter还具备黑盒第三方脚本、筛选业务脚本等实用的开发调试能力，同时支持远程浏览器控制（基于本地CDP中继），既满足个人开发者的轻量自动化需求，也能适配企业级的批量测试、数据采集场景。

三、技术细节

Playwriter的技术架构围绕“AI/MCP客户端 - 本地中继服务 - Chrome扩展 - 浏览器CDP接口” 四层设计，抛弃了传统自动化工具的隔离进程模式，采用Relay Server（中继服务器） 架构，同时结合Accessibility Tree、CDP协议、MCP协议等核心技术，实现了AI与浏览器的稳定、高效、精准交互，其技术细节主要包括核心架构、核心技术原理、项目代码结构三部分。

3.1 核心架构

Playwriter的整体架构为分层式本地通信架构，无外部服务依赖，各组件之间通过标准化协议通信，可独立部署也可协同运行，核心组件包括MCP/AI客户端、Playwriter中继服务、Chrome扩展、Chrome CDP接口，各组件的作用与通信关系如下：

1. MCP/AI客户端：指支持Model Context Protocol协议的AI工具（如Claude Desktop）、自定义的Node.js/TypeScript脚本，是指令的发起端，负责发送浏览器操作指令；

2. Playwriter中继服务：项目的核心服务层，基于Node.js开发，运行在本地localhost:19988端口，作为指令的“中转站”，实现MCP协议与CDP协议的转换，同时管理浏览器连接状态；

3. Chrome扩展（Playwriter MCP）：作为浏览器与中继服务的桥梁，通过Chrome的debugger权限对接浏览器CDP接口，接收中继服务的指令并执行，同时将浏览器的页面状态回传；

4. Chrome CDP接口：Chrome浏览器原生的开发者工具协议接口，是Playwriter操作浏览器底层渲染引擎、实现各类自动化行为的基础。

各组件的通信流程为：AI/MCP客户端 → 本地WebSocket → Playwriter中继服务 → Chrome扩展 → Chrome CDP接口 → 浏览器，反向的页面状态回传则遵循该流程逆向执行，全程无外部网络参与，通信效率与稳定性均远高于传统的远程CDP连接模式。

3.2 核心技术原理

Playwriter的核心技术突破在于Accessibility Tree的应用与MCP协议的落地，同时对CDP协议的调用做了深度优化，这也是其区别于传统Playwright、Puppeteer的关键：

1. Accessibility Tree（无障碍树）技术：传统AI自动化工具依赖截图和视觉模型识别像素信息定位元素，易受页面样式、分辨率影响，而Playwriter将网页的DOM树转换为结构化的无障碍树，仅向AI传输元素的语义角色、属性关系、交互状态等核心信息，既减少了90%的Token占用，又让AI能精准理解页面布局，从“视觉识别”升级为“结构化理解”；

2. MCP协议适配：Model Context Protocol（MCP）是面向大语言模型的工具调用协议，Playwriter深度适配该协议，为AI工具提供了标准化的浏览器操作接口，让AI无需理解复杂的CDP协议，只需通过自然语言指令即可编写Playwright代码、控制浏览器；

3. CDP协议轻量化调用：通过Chrome扩展直接接管浏览器的CDP接口，避免了传统Playwright启动独立浏览器进程、手动配置CDP端口的操作，同时对CDP指令做了批量优化，减少了指令传输的冗余步骤，提升了操作执行效率；

4. 登录态复用技术：Chrome扩展运行在浏览器的主进程中，可直接访问当前标签页的Cookies、SessionStorage、LocalStorage等数据，因此Playwriter的自动化操作能完全复用浏览器的现有登录状态，解决了传统无头浏览器无法操作鉴权网站的核心痛点。

3.3 项目代码结构

Playwriter采用pnpm workspace管理的monorepo架构，所有代码按功能模块划分，核心目录清晰，便于开发、调试与二次开发，同时项目提供了完整的示例脚本、测试用例与开发文档，降低了使用门槛。其核心代码结构如下：

playwriter/
├── playwriter/    # 核心工具层：Node.js中继服务、MCP协议适配、示例脚本
│  ├── src/     # 核心源码：CDP中继、协议转换、浏览器路径配置、调试工具
│  │  ├── prompt.md # MCP协议AI工具的使用文档，指导AI编写Playwright代码
│  │  ├── resource.md # Playwright最佳实践，如元素定位、指令编写
│  │  └── *.ts   # 各类功能实现的TypeScript源码
│  ├── scripts/   # 快速使用示例脚本：连接扩展、新建标签页、截图、获取页面信息等
│  ├── test/     # 项目测试用例：MCP协议测试、CDP连接测试、扩展功能测试
│  └── package.json # 依赖管理与脚本命令配置
├── extension/    # Chrome扩展源码：对接浏览器CDP、与中继服务通信
│  ├── src/     # 扩展核心逻辑：debugger权限管理、指令接收与执行
│  ├── dist/     # 构建后的扩展文件（pnpm build后生成，可直接加载到Chrome）
│  └── permissions.md # Chrome应用商店提权说明，仅申请核心必要权限
├── website/     # 项目官方网站代码，含使用教程、功能介绍
├── .github/     # CI/CD配置：基于GitHub Actions，适配Node.js 20 + pnpm 9
├── docs/       # 项目详细文档：安装、使用、二次开发指南
├── README.md     # 项目主文档：快速入门、核心功能、使用示例
└── pnpm-workspace.yaml # monorepo架构配置文件

其中，playwriter/src/prompt.md与playwriter/src/resource.md是AI协同的关键文件，前者为AI工具提供了MCP接口的使用规范，后者则是Playwright的通用最佳实践，可帮助AI更高效地编写浏览器操作代码。

四、应用场景

Playwriter凭借复用浏览器状态、AI深度协同、轻量化、本地化的核心优势，完美适配AI辅助办公、自动化测试、数据采集、开发调试四大核心场景，同时可满足个人开发者、测试工程师、企业办公人员等不同角色的需求，部分场景还能解决传统工具无法实现的业务痛点，各核心应用场景的具体使用方式与价值如下：

4.1 AI辅助办公

这是Playwriter最核心的应用场景，也是其区别于传统自动化工具的关键。通过对接Claude Desktop等MCP协议AI工具，用户可通过自然语言向AI下达指令，让AI直接操作已登录的浏览器，完成各类办公任务，无需手动编写任何代码。

• 适用场景：自动处理企业后台审批、发送邮件、整理网页数据、填写在线表单、批量操作电商平台后台等；

• 核心价值：复用浏览器的企业系统、邮箱、平台登录态，无需重新配置鉴权信息，AI操作与人工操作完全一致，大幅减少重复办公工作的时间成本；

• 使用示例：向Claude发送“帮我打开公司OA后台，把待审批的流程全部通过，并把审批结果整理成表格保存到桌面”，AI即可通过Playwriter完成所有操作。

4.2 自动化测试

Playwriter可作为传统Playwright的轻量化替代方案，用于Web项目的端到端自动化测试，尤其适合需要鉴权的页面测试，解决了传统自动化测试中“每次测试重新登录、环境配置复杂”的痛点。

• 适用场景：企业后台系统功能测试、电商平台用户端流程测试、需要登录的网页功能回归测试等；

• 核心价值：复用浏览器的登录态，无需在测试脚本中编写登录逻辑，测试用例更简洁；支持有头可视化测试，便于调试测试用例；兼容完整Playwright API，可直接迁移原有Playwright测试脚本；

• 使用优势：相比传统Playwright，无需启动独立浏览器进程，测试资源占用减少80%，测试执行效率提升数倍。

4.3 数据采集

在需要鉴权的网页数据采集场景中，Playwriter的优势尤为突出，传统的无头浏览器采集方式易被网站识别，且无法绕过登录验证，而Playwriter可在用户已登录的状态下完成数据采集，更贴近人工操作，降低被反爬的概率。

• 适用场景：采集企业内部系统的业务数据、采集需要登录的电商平台店铺数据、采集个人社交平台的信息等；

• 核心价值：复用登录态，无需处理验证码、滑块验证等鉴权环节；支持AI辅助采集，可通过自然语言指令让AI定位并采集指定数据；所有采集操作本地完成，数据安全性高。

4.4 开发调试

对于前端开发者而言，Playwriter是一款实用的网页开发调试工具，其提供的黑盒第三方脚本、筛选业务脚本、精准元素定位等能力，可大幅提升网页调试效率。

• 适用场景：调试包含大量第三方脚本的复杂网页、定位网页中难以识别的可交互元素、验证网页的无障碍性（基于Accessibility Tree）等；

• 核心价值：可通过CDP协议黑盒第三方脚本，仅调试自身业务代码；将网页转换为Accessibility Tree，便于开发者理解页面的语义结构，优化网页的无障碍设计；支持实时执行Playwright代码，快速验证网页元素的交互逻辑。

4.5 其他拓展场景

除上述核心场景外，Playwriter还可应用于浏览器远程控制（基于本地CDP中继，实现可控的远程浏览器操作）、网页自动化监控（监控已登录网页的指定信息变化，如后台订单、系统通知）、AI辅助网页开发（让AI直接在浏览器中调试网页代码、预览效果）等场景，具备极强的场景拓展性。

五、使用方法

Playwriter的使用分为基础环境准备、Chrome扩展安装、三种核心使用方式三部分，整体操作流程简单，无需复杂的环境配置，个人开发者可快速上手。该工具的基础运行环境要求为：Node.js 20+、pnpm 9+、Chrome浏览器（最新版），建议使用Windows/macOS/Linux主流桌面系统。

5.1 基础环境准备

1. 安装Node.js：前往Node.js官方网站下载并安装20及以上版本，安装完成后执行node -v验证版本；

2. 安装pnpm：执行全局安装命令npm install -g pnpm，安装完成后执行pnpm -v验证版本；

3. 克隆项目仓库：执行git clone https://github.com/remorses/playwriter.git，将项目代码克隆到本地；

4. 安装项目依赖：进入项目根目录，执行pnpm install，自动安装所有模块的依赖包；

5. 构建项目：执行pnpm build，构建Chrome扩展文件与核心工具代码，构建完成后会在extension/dist生成可加载的Chrome扩展文件。

5.2 Chrome扩展安装

Playwriter的核心依赖为Chrome扩展（Playwriter MCP），可通过Chrome应用商店安装（推荐）或本地加载已构建的扩展文件两种方式安装：

1. Chrome应用商店安装：直接在Chrome应用商店搜索「Playwriter MCP」，点击安装即可，安装完成后将扩展图标固定到Chrome工具栏；

2. 本地加载扩展：打开Chrome浏览器，输入chrome://extensions/进入扩展管理页面，开启「开发者模式」，点击「加载已解压的扩展程序」，选择项目中的extension/dist目录即可。

扩展安装完成后，点击工具栏中的Playwriter MCP图标，图标变为绿色即表示扩展已成功连接到本地浏览器，红色则表示未连接，点击即可完成连接。

5.3 三种核心使用方式

Playwriter支持MCP协议AI工具对接、程序化调用、标准CDP连接三种使用方式，覆盖AI协同、代码开发、传统自动化等不同需求，三种方式可独立使用，也可结合使用，以下为各方式的详细使用步骤：

5.3.1 方式一：MCP协议AI工具对接（推荐，无代码）

该方式是Playwriter的核心使用方式，无需编写任何代码，只需将AI工具与Playwriter的MCP服务对接，即可通过自然语言让AI控制浏览器，以Claude Desktop为例，步骤如下：

1. 启动Playwriter MCP服务：进入项目playwriter目录，执行npx playwriter@latest，启动本地MCP中继服务，服务运行在localhost:19988；

2. 找到Claude配置文件：打开Claude Desktop，找到claude_desktop_config.json配置文件（不同系统路径不同，可参考Claude官方文档）；

3. 配置MCP服务器：在配置文件中添加Playwriter的MCP服务配置，代码如下：

{
 "mcpServers": {
  "playwriter": {
   "command": "npx",
   "args": ["-y", "playwriter@latest"]
  }
 }
}

4. 重启Claude Desktop：配置完成后重启Claude，即可在对话中使用Playwriter功能；

5. AI控制浏览器：在Claude对话框中发送自然语言指令（如“帮我打开百度，搜索Playwriter并截图保存”），Claude会自动通过Playwriter控制已连接的Chrome浏览器完成操作。

5.3.2 方式二：程序化调用（TypeScript/Node.js，自定义脚本）

该方式适合开发者通过编写TypeScript/Node.js脚本实现自定义的浏览器自动化操作，Playwriter提供了简洁的API，可直接连接到Chrome浏览器，步骤如下：

1. 启动Playwriter中继服务：执行npx playwriter@latest启动本地服务；

2. 创建脚本文件：在项目中创建demo.ts文件，编写自动化脚本，核心示例代码如下（实现访问示例站并截图）：

// 导入核心依赖
import { chromium } from 'playwright-core'
import { startPlayWriterCDPRelayServer, getCdpUrl } from 'playwriter'

// 主函数
async function main() {
 // 启动Playwriter中继服务
 const server = await startPlayWriterCDPRelayServer()
 // 通过CDP连接到当前Chrome浏览器实例
 const browser = await chromium.connectOverCDP(getCdpUrl())
 // 获取当前浏览器的上下文与活动页面
 const context = browser.contexts()[0]
 const page = context.pages()[0]

 // 执行自定义操作：访问示例站、截图
 await page.goto('https://example.com')
 await page.screenshot({ path: 'example-screenshot.png' })
 console.log('截图完成，保存为example-screenshot.png')

 // 关闭中继服务（请勿调用browser.close()，避免关闭用户的Chrome浏览器）
 server.close()
}

// 执行主函数
main().catch(console.error)

3. 运行脚本：执行tsx demo.ts（需提前安装tsx：npm install -g tsx），脚本即可自动执行，完成浏览器操作。

关键注意点：程序化调用时，**请勿调用browser.close()**，否则会直接关闭用户正在使用的Chrome浏览器，只需关闭中继服务即可。

5.3.3 方式三：标准CDP连接（兼容传统自动化工具）

Playwriter支持标准的CDP协议连接，可将其作为CDP中继服务，对接任何支持CDP协议的自动化工具（如原生Playwright、Puppeteer），步骤如下：

1. 启动Playwriter中继服务：执行npx playwriter@latest，服务启动后会暴露标准的CDP连接地址ws://localhost:19988；

2. 对接CDP工具：在原生Playwright/Puppeteer中，通过该CDP地址连接到Chrome浏览器，以原生Playwright为例，核心代码如下：

import { chromium } from 'playwright-core'

async function main() {
 // 连接到Playwriter暴露的CDP地址
 const browser = await chromium.connectOverCDP('ws://localhost:19988')
 const page = browser.contexts()[0].pages()[0]
 // 执行CDP操作
 await page.goto('https://github.com')
 await page.title().then(title => console.log('页面标题：', title))
}

main().catch(console.error)

3. 运行代码：即可通过标准CDP协议实现浏览器自动化操作，同时复用Chrome的登录态。

六、常见问题解答

Q1：点击Playwriter MCP扩展图标，图标始终为红色，无法连接到浏览器

表现：扩展图标红色，提示“未连接到浏览器”，点击后无反应；
原因：1. Chrome浏览器未开启debugger权限；2. 扩展未获取到debugger权限；3. 浏览器版本过旧；
解决方案：

1. 确保Chrome浏览器为最新版，可通过chrome://settings/help检查并更新；

2. 进入Chrome扩展管理页面（chrome://extensions/），找到Playwriter MCP，点击「详情」，确保「允许访问文件网址」「在隐身模式下运行」已开启；

3. 关闭Chrome后重新打开，再次点击扩展图标尝试连接。

Q2：执行npx playwriter@latest启动服务，报错“Error: listen EADDRINUSE: address already in use :::19988”

表现：服务启动失败，提示端口19988被占用；
原因：本地已有其他进程占用了19988端口（Playwriter的默认端口）；
解决方案：

1. 查找占用端口的进程：Windows执行netstat -ano | findstr "19988"，macOS/Linux执行lsof -i:19988；

2. 结束占用进程：根据进程ID结束进程，或直接重启电脑释放端口；

3. （可选）修改Playwriter的默认端口：在项目playwriter/src中找到端口配置文件，将19988修改为其他未占用端口。

Q3：Claude等AI工具已配置MCP服务，但无法控制浏览器，提示“无法连接到Playwriter服务器”

表现：AI指令发送后，提示服务连接失败，无任何浏览器操作；
原因：1. Playwriter MCP服务未启动；2. AI配置文件中的MCP服务地址错误；3. 防火墙拦截了本地19988端口通信；
解决方案：

1. 确认已执行npx playwriter@latest启动服务，且终端无报错，服务处于运行状态；

2. 检查Claude配置文件中的MCP服务配置，确保command和args配置正确，无拼写错误；

3. 暂时关闭本地防火墙/杀毒软件，尝试重新发送AI指令。

Q4：程序化调用时，脚本执行报错“Element is not clickable”（元素不可点击）

表现：脚本执行到点击/输入步骤时，提示元素不可点击，执行失败；
原因：1. 元素未在浏览器视口内；2. 元素被加载遮罩、弹窗遮挡；3. 页面未完全渲染完成；
解决方案：

1. 利用Playwright的自动等待机制，添加显式等待，确保元素可交互，示例代码：

// 等待元素可点击，最多等待10秒
await page.getByTestId('btn-submit').waitFor({ state: 'visible', timeout: 10000 })
await page.getByTestId('btn-submit').click()

2. 若元素在视口外，先执行滚动操作，将元素滚动到视口内：await page.getByTestId('btn-submit').scrollIntoViewIfNeeded()；

3. 检查页面是否有加载遮罩/弹窗，先关闭遮罩/弹窗再执行点击操作。

Q5：克隆项目后，执行pnpm install报错，依赖安装失败

表现：依赖安装过程中，提示部分包下载失败，或出现“pnpm: command not found”；
原因：1. pnpm未全局安装；2. 网络问题导致包下载失败；3. Node.js版本过低；
解决方案：

1. 确认已全局安装pnpm，执行pnpm -v验证，未安装则执行npm install -g pnpm；

2. 确认Node.js版本为20+，版本过低则升级Node.js；

3. 切换npm镜像源，执行pnpm config set registry https://registry.npmmirror.com/，再重新执行pnpm install。

Q6：AI控制浏览器时，无法精准定位页面元素，操作偏离预期

表现：AI能执行浏览器操作，但定位的元素错误，如点击了无关按钮、输入到错误输入框；
原因：网页未生成规范的Accessibility Tree，AI无法正确理解页面结构；
解决方案：

1. 刷新网页后重新让AI执行操作，确保页面完全渲染；

2. 向AI补充页面元素描述，如“点击页面顶部导航栏的「我的」按钮，该按钮在「首页」右侧”；

3. 对于自定义开发的网页，优化页面的无障碍属性，为核心元素添加aria-label等属性，让Accessibility Tree更规范。

Q7：本地加载Chrome扩展后，Chrome提示“扩展程序未列在Chrome网上应用店中，可能存在风险”

表现：加载本地扩展后，浏览器顶部出现风险提示，扩展功能可正常使用；
原因：Chrome对本地加载的非应用商店扩展的安全提示，无实际风险；
解决方案：

1. 点击提示中的「详细信息」，选择「仍要使用」即可；

2. 若想关闭提示，可直接通过Chrome应用商店安装Playwriter MCP扩展。

七、相关链接

1. 项目GitHub仓库：https://github.com/remorses/playwriter

2. Chrome应用商店Playwriter MCP扩展：https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe

3. 项目核心示例脚本：https://github.com/remorses/playwriter/tree/main/playwriter/scripts

4. MCP协议介绍：https://www.aipuzi.cn/ai-tutorial/what-is-mcp.html

八、总结

Playwriter是由remorses开发的一款面向AI时代的开源浏览器自动化工具集，以TypeScript为开发语言、Apache-2.0为开源协议，核心由Chrome扩展与本地Node.js中继服务组成，通过Relay Server架构与CDP协议实现了Playwright与用户当前Chrome浏览器的无缝连接，既解决了传统自动化工具资源占用高、环境配置复杂、无法复用浏览器登录态的核心痛点，又实现了与MCP协议AI工具的深度融合，让AI能通过自然语言直接控制浏览器。该工具在性能上做了极致优化，上下文窗口占用减少80%且API能力提升10倍，同时坚持纯本地运行的原则，所有操作与通信均在用户本地完成，无数据外发与追踪，隐私性与安全性拉满；在功能上兼容完整的Playwright API，支持有头/无头双模运行、精准的Accessibility Tree网页感知、多方式连接调用，可满足AI辅助办公、自动化测试、数据采集、开发调试等多场景需求。Playwriter的使用门槛极低，无需复杂的环境配置，既支持无代码的AI自然语言控制，也支持开发者的程序化自定义脚本开发，同时提供了完整的文档、示例与常见问题解决方案，是个人开发者与企业团队实现浏览器自动化的优质选择，其将LLM与真实浏览器环境无缝衔接的设计，也为AI时代的自动化工具发展提供了新的思路。