# @bearbuild/playwright-mcp 中文文档

规范地址：https://npmcn.com/package/%40bearbuild/playwright-mcp/

版本：1\.0\.2
npm 元数据更新时间：2026-10-07T20:44:16.123Z
中文译文更新时间：2026-11-07T19:48:24.952Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bearbuild/playwright-mcp
原文对照：https://npmcn.com/package/%40bearbuild/playwright-mcp/?lang=original
项目主页：https://playwright.dev/
源码仓库：https://github.com/bearbuild/playwright-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：195 kB，79 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：8 个
- 首次发布：2026-10-07T20:41:28.593Z
- 最新版本发布：2026-10-07T20:44:15.937Z
- 近 30 天下载量：11378（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Cloudflare Playwright 工具用于 MCP( 熊建叉)

## 安装

```sh
npm install @bearbuild/playwright-mcp
```

也可以使用：`pnpm add @bearbuild/playwright-mcp`、`yarn add @bearbuild/playwright-mcp`、`bun add @bearbuild/playwright-mcp`

## README

## Cloudflare 剧作家 MCP

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/playwright-mcp/tree/main/cloudflare/example)

### 概览

该项目利用Playwright进行自动浏览器测试,并与Cloudflare Workers整合, [浏览器渲染](https://developers.cloudflare.com/browser-rendering/) 财务报告和审定财务报表 [`@cloudflare/playwright`](https://github.com/cloudflare/playwright) 用于部署.

### 建设和部署

按照这些步骤设立和部署该项目:

1.  安装依赖性 :

```bash
npm ci
```

2.  构建 :

```bash
cd cloudflare
npm run build
```

3.  部署到云浮工人:

```bash
cd cloudflare/example
npm ci
npx wrangler deploy
```

### 用 Cloudflare AI 游戏场

![alt text](https://npmcn.com/package/%40bearbuild/playwright-mcp/docs/imgs/playground-ai-screenshot.png)

[Cloudflare操场 AI](https://playground.ai.cloudflare.com/) 是使用工人AI中可用的LLM模型测试MCP服务器的好方法.

-   导航到 [https://playground.ai.cloudflare.com/ 页面存档备份,存于互联网档案馆](https://playground.ai.cloudflare.com/)
-   确保模式设定为 `llama-3.3-70b-instruct-fp8-fast`
-   单位 **MCP 服务器**设置 **網址** 改为 `https://[my-mcp-url].workers.dev/sse`
-   点击 **连接**
-   状况应更新至 **已连接** 它应列出14个可用的工具

你现在可以开始与模型互动,它将运行必要的工具来完成所要求的任务.

> \[TIP\] 对于最佳结果,给出由单个动作组成的简单指令,如"创建新的待办事宜条目","去云浮站","取一截图"等

对话的例子:

| 作用 | 消息 |
| --- | --- |
| **用户** | 去演示. playwright.dev/todomvc |
| **助理** | _运行浏览器 navigate 工具_  
页面已被导航到 [https://demo.playwright.dev/todomvc/ (中文(简体) )](https://demo.playwright.dev/todomvc/),页面标题为"React ^ TodoMVC". 页面快照显示页面内容,包括标题,文本框,以及多个链接. |
| **用户** | 创建一些待办事宜条目 |
| **助理** | _运行浏览器 类型工具_  
新建了"买杂货"的待办事宜条目. 页面快照显示页面更新内容,包括新待办事宜条目. |
| **用户** | 不错 现在用鹦鹉风格创建待办事宜 |
| **助理** | _运行浏览器 类型工具_  
以鹦鹉风格创建了"Polly想吃快克"的新多克条目. 页面快照显示页面更新内容,包括新待办事宜条目. |
| **用户** | 用 Yoda 风格创建另一个待办事宜 |
| **助理** | _运行浏览器 类型工具_  
一个新的"行走,我必须走"的待办事宜条目是以尤达风格创建的. 页面快照显示页面更新内容,包括新待办事宜条目. |
| **用户** | 拍个截图 |
| **助理** | _运行浏览器 take 截图工具_  
![alt text](https://npmcn.com/package/%40bearbuild/playwright-mcp/docs/imgs/todomvc-screenshot-1.png) 已拍摄当前页面的截图 。 截图采用PNG格式,大小为56KB. |
| **用户** | 现在单击鹦鹉待办事宜条目的复选框 |
| **助理** | _运行浏览器 单击工具_  
鹦鹉待办事宜条目"Polly想要个快克"的复选框已点击. 页面快照显示页面的更新内容, 现在选中复选框 . |
| **用户** | 拍个截图 |
| **助理** | _运行浏览器 take 截图工具_  
![alt text](https://npmcn.com/package/%40bearbuild/playwright-mcp/docs/imgs/todomvc-screenshot-2.png) 已拍摄当前页面的截图 。 截图采用PNG格式,尺寸为58KB. |
| **用户** | 删除已完成的待办事宜条目 |
| **助理** | _运行浏览器 单击工具_  
"Clear finished"按钮已点击. 页面快照显示页面的更新内容,所完成的待办事宜条目"Polly想要个快克"被移除. |
| **用户** | 最后一张截图 |
| **助理** | _运行浏览器 take 截图工具_  
![alt text](https://npmcn.com/package/%40bearbuild/playwright-mcp/docs/imgs/todomvc-screenshot-3.png) 已拍摄当前页面的最后截图 。 截图采用PNG格式并大小为50KB. |

### 与 Claude 桌面使用

现在, [克劳德桌面](https://claude.ai/download) 只支持本地的MCP服务器. 用于 `playground-mcp` 我们用克洛德桌面 [mcp 远程](https://github.com/geelen/mcp-remote),这个工具可以代理远程MCP服务器并在本地曝光. 使用以下配置 :

1.  打开克劳德桌面的配置文件 .
2.  在下方添加以下 JSON 片断 `mcpServers` 节:

```json
{
  "mcpServers": {
    "cloudflare-playwright-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://[my-mcp-url].workers.dev/sse"
      ]
    }
  }
}
```

3.  保存配置文件并 **重新启动** 克劳德桌面应用更改.

这个设置确保了克洛德桌面可以与Cloudflare Playwright MCP服务器进行通信.

以下是一个会话打开TODO演示应用,加入"购买柠檬"并进行截图,利用剧作家-mcp工具和浏览器Rendering:

![alt text](https://npmcn.com/package/%40bearbuild/playwright-mcp/docs/imgs/claudemcp.gif)

### 在 VSCode 中配置

您可以使用 Playwright MCP 服务器安装 [VS 代码 CLI](https://code.visualstudio.com/docs/configure/command-line)数字 :

```bash
# For VS Code
code --add-mcp '{"name":"cloudflare-playwright","type":"sse","url":"https://[my-mcp-url].workers.dev/sse"}'
```

```bash
# For VS Code Insiders
code-insiders --add-mcp '{"name":"cloudflare-playwright","type":"sse","url":"https://[my-mcp-url].workers.dev/sse"}'
```

在安装后, Playwright MCP 服务器将可用您的 GitHub 副驾驶代理在 VS 代码中使用 .

### 用光标

默认时间 `imageResponses` 设置为 `"auto"`,服务器将禁用 Cursor 客户端的内置图像响应。 要启用 Cursor 中的内置截图, 您需要覆盖此行为 :

如果你经营自己的云旗工人,请通过 `imageResponses: "allow"` 创建 MCP 代理时 :

```typescript
export const PlaywrightMCP = createMcpAgent(env.BROWSER, {
  imageResponses: 'allow',
} as any);
```

### 工具模式

这些工具有两种模式:

1.  **抓图模式** (默认):利用无障碍快照提高性能和可靠性
2.  **愿景模式**: 使用截图进行视觉交互

愿景 模式与能够与使用元素交互的计算机使用模式最有效 X Y 坐标空间,基于所提供的截图.

**互动**

-   **浏览器( s)**
    -   标题: 页面快照
    -   描述: 抓取当前页面的可访问性快照, 这比截图更好
    -   参数:无
    -   只读 : **真实**

-   **浏览器 单击**
    -   标题:单击
    -   描述: 在网页上单击
    -   参数:
        -   `element` (字符串):人类可读元素描述,用于获得与元素互动的许可
        -   `ref` (字符串):页面快照中精确的目标元素参考
        -   `doubleClick` (布尔,可选): 是否执行双击而不是单击
    -   只读 : **虚假**

-   **浏览器( d)**
    -   标题: 拖动鼠标
    -   描述: 在两个元素之间拖放
    -   参数:
        -   `startElement` (字符串):人类可读源元素描述,用于获得与元素互动的许可
        -   `startRef` (字符串):页面快照中精确的源元素参考
        -   `endElement` (字符串):人类可读目标元素描述,用于获得与元素交互的许可
        -   `endRef` (字符串):页面快照中精确的目标元素参考
    -   只读 : **虚假**

-   **浏览器( h)**
    -   标题: Hover 鼠标
    -   说明: 页面上对元素的依赖
    -   参数:
        -   `element` (字符串):人类可读元素描述,用于获得与元素互动的许可
        -   `ref` (字符串):页面快照中精确的目标元素参考
    -   只读 : **真实**

-   **浏览器类型**
    -   标题: 类型文本
    -   描述: 将文本输入可编辑元素
    -   参数:
        -   `element` (字符串):人类可读元素描述,用于获得与元素互动的许可
        -   `ref` (字符串):页面快照中精确的目标元素参考
        -   `text` (字符串):输入元素的文字
        -   `submit` (布尔,可选): 是否提交已输入的文本( 后按 Enter)
        -   `slowly` (布尔,可选): 是否一次输入一个字符 。 用于触发页面中的密钥处理器 。 默认情况下, 整个文本立即填入 .
    -   只读 : **虚假**

-   **浏览器( s)**
    -   标题: 选择选项
    -   描述: 在下拉时选择一个选项
    -   参数:
        -   `element` (字符串):人类可读元素描述,用于获得与元素互动的许可
        -   `ref` (字符串):页面快照中精确的目标元素参考
        -   `values` (数组):在下拉时要选择的数值组. 这可以是单个值或多个值.
    -   只读 : **虚假**

-   **浏览器 press key**
    -   标题:按键
    -   描述: 按键盘上的键
    -   参数:
        -   `key` (字符串):按键或要生成的字符的名称,例如 `ArrowLeft` 或者说 `a`
    -   只读 : **虚假**

-   **浏览器( w)**
    -   标题:等待
    -   描述: 等待文本出现或消失或指定通过时间
    -   参数:
        -   `time` (数目,可选): 等几秒钟的时间
        -   `text` (弦,可选): 等待的文本
        -   `textGone` (弦,可选): 等待消失的文本
    -   只读 : **真实**

-   **浏览器 file 上载**
    -   标题: 上传文件
    -   描述: 上传一个或多个文件
    -   参数:
        -   `paths` (阵列):要上传的文件的绝对路径. 可以是单个文件,也可以是多个文件.
    -   只读 : **虚假**

-   **浏览器 handle dialog**
    -   标题: 处理对话框
    -   描述: 处理对话框
    -   参数:
        -   `accept` 是否接受对话框 .
        -   `promptText` (弦,可选): 出现快速对话框时的提示文本 .
    -   只读 : **虚假**

**导航**

-   **浏览器( n)**
    -   标题: 导航到 URL
    -   描述: 导航到 URL
    -   参数:
        -   `url` (字符串):要导航的 URL
    -   只读 : **虚假**

-   **浏览器 navigate back**
    -   标题: 返回
    -   描述: 回到上一页
    -   参数:无
    -   只读 : **真实**

-   **浏览器 navigate forward**
    -   标题:前进
    -   描述: 转到下一页
    -   参数:无
    -   只读 : **真实**

**资源**

-   **浏览器 take 屏幕shot**
    -   标题:取一个截图
    -   描述:取出当前页面的截图. 您不能执行基于截图的动作, 使用浏览器 snapshot 进行动作 .
    -   参数:
        -   `raw` (布尔,可选): 是否不压缩返回( PNG 格式) 。 默认为假, 它返回 JPEG 图像 .
        -   `filename` (弦,可选): 要保存截图的文件名 。 默认为 `page-{timestamp}.{png|jpeg}` 如果未指明的话.
        -   `element` (弦,可选): 人类可读元素描述用于获取截取元素的许可. 如果不提供,截图将取自取景口. 如果提供了要件,也必须提供参考.
        -   `ref` (弦,可选): 页面快照中精确的目标元素参考. 如果不提供,截图将取自取景口. 如果提供了参考文献,也必须提供要素.
    -   只读 : **真实**

-   **浏览器 pdf 保存**
    -   标题: 另存为 PDF
    -   描述: 将页面保存为 PDF
    -   参数:
        -   `filename` (弦,可选): 要保存 pdf 的文件名 。 默认为 `page-{timestamp}.pdf` 如果未指明的话.
    -   只读 : **真实**

-   **浏览器 网络 请求**
    -   标题:列表网络请求
    -   描述: 自装入页面后返回所有网络请求
    -   参数:无
    -   只读 : **真实**

-   **浏览器( c)**
    -   标题: 获取控制台消息
    -   描述: 返回所有控制台信件
    -   参数:无
    -   只读 : **真实**

**公用事业**

-   **浏览器 install**
    -   标题: 安装配置中指定的浏览器
    -   描述: 安装配置中指定的浏览器 。 如果您发现浏览器没有安装错误, 请使用此选项 .
    -   参数:无
    -   只读 : **虚假**

-   **浏览器( c)**
    -   标题: 关闭浏览器
    -   描述: 关闭页面
    -   参数:无
    -   只读 : **真实**

-   **浏览器大小( r)**
    -   标题: 更改浏览器窗口大小
    -   描述: 调整浏览器窗口大小
    -   参数:
        -   `width` (数目):浏览器窗口的宽度
        -   `height` (数目):浏览器窗口的高度
    -   只读 : **真实**

**标签**

-   **浏览器 tab list**
    -   标题:列表标签
    -   描述: 列表浏览器标签
    -   参数:无
    -   只读 : **真实**

-   **浏览器 tab new**
    -   标题: 打开新标签
    -   描述: 打开新标签
    -   参数:
        -   `url` (弦,可选): 在新标签中导航的 URL 。 如果不提供,新标签将是空白的.
    -   只读 : **真实**

-   **浏览器 tab 选择**
    -   标题: 选择标签
    -   描述: 按索引选择标签
    -   参数:
        -   `index` (数目):要选择的标签索引
    -   只读 : **真实**

-   **浏览器 tab 关闭**
    -   标题: 关闭标签
    -   描述: 关闭标签
    -   参数:
        -   `index` (数目,可选): 关闭标签的索引 。 如果不提供则关闭当前标签.
    -   只读 : **虚假**

**测试**

-   **浏览器 基因 播放wright test**
    -   标题: 生成一个 Playwright 测试
    -   描述: 生成给定情景的 Playwright 测试
    -   参数:
        -   `name` (字符串):测试的名称
        -   `description` (弦):试验的描述
        -   `steps` (阵列):测试的步骤
    -   只读 : **真实**

**视野模式**

-   **浏览器 屏幕 抓取**
    -   标题:取一个截图
    -   描述: 查看当前页面的截图
    -   参数:无
    -   只读 : **真实**

-   **浏览器 屏幕 移动 mouse**
    -   标题: 移动鼠标
    -   描述: 将鼠标移动到指定位置
    -   参数:
        -   `element` (字符串):人类可读元素描述,用于获得与元素互动的许可
        -   `x` (数目):X坐标
        -   `y` (数目):Y坐标
    -   只读 : **真实**

-   **浏览器 屏幕 单击**
    -   标题:单击
    -   描述: 单击鼠标左键
    -   参数:
        -   `element` (字符串):人类可读元素描述,用于获得与元素互动的许可
        -   `x` (数目):X坐标
        -   `y` (数目):Y坐标
    -   只读 : **虚假**

-   **浏览器 屏幕 拖网**
    -   标题: 拖动鼠标
    -   描述: 拖动鼠标左键
    -   参数:
        -   `element` (字符串):人类可读元素描述,用于获得与元素互动的许可
        -   `startX` 开始 X 坐标
        -   `startY` (数目):开始 Y 坐标
        -   `endX` (数目):结束 X 坐标
        -   `endY` (数目):结束 Y 坐标
    -   只读 : **虚假**

-   **浏览器 屏幕 类型**
    -   标题: 类型文本
    -   说明: 文本类型
    -   参数:
        -   `text` (字符串):输入元素的文字
        -   `submit` (布尔,可选): 是否提交已输入的文本( 后按 Enter)
    -   只读 : **虚假**

-   **浏览器 press key**
    -   标题:按键
    -   描述: 按键盘上的键
    -   参数:
        -   `key` (字符串):按键或要生成的字符的名称,例如 `ArrowLeft` 或者说 `a`
    -   只读 : **虚假**

-   **浏览器( w)**
    -   标题:等待
    -   描述: 等待文本出现或消失或指定通过时间
    -   参数:
        -   `time` (数目,可选): 等几秒钟的时间
        -   `text` (弦,可选): 等待的文本
        -   `textGone` (弦,可选): 等待消失的文本
    -   只读 : **真实**

-   **浏览器 file 上载**
    -   标题: 上传文件
    -   描述: 上传一个或多个文件
    -   参数:
        -   `paths` (阵列):要上传的文件的绝对路径. 可以是单个文件,也可以是多个文件.
    -   只读 : **虚假**

-   **浏览器 handle dialog**
    -   标题: 处理对话框
    -   描述: 处理对话框
    -   参数:
        -   `accept` 是否接受对话框 .
        -   `promptText` (弦,可选): 出现快速对话框时的提示文本 .
    -   只读 : **虚假**

## 常见问题

### @bearbuild/playwright-mcp 是什么？

Cloudflare Playwright 工具用于 MCP\( 熊建叉\)

### 如何安装 @bearbuild/playwright-mcp？

在项目目录运行 npm install @bearbuild/playwright-mcp，或使用 pnpm add / yarn add / bun add。

### @bearbuild/playwright-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bearbuild/playwright-mcp 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bearbuild/playwright-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bearbuild/playwright-mcp 可以商用吗？

@bearbuild/playwright-mcp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bearbuild/playwright-mcp 的下载量有多少？

根据 npm 官方下载统计，@bearbuild/playwright-mcp 在 2026/10/08 – 2026/11/06 这 30 天内被下载 11,378 次，日均约 379 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bearbuild/playwright-mcp 还在维护吗？

最新版本 1\.0\.2 发布于 2026/10/08（30 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/10/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。