@ai-coding-labs/playwright-mcp-plus

v0.0.44

Published

7 months ago

Enhanced Playwright Tools for MCP with Project Session Isolation

Downloads

119

0High
0Medium
0Low

cc11001100

playwright mcp model-context-protocol browser-automation project-isolation session-management chrome-extensions extension-management browser-extensions

Playwright MCP Plus

🌐 Language / 语言: English | 中文

🎭 看看区别！

😫 没有 Playwright Plus MCP

单浏览器限制： 一次只能运行一个浏览器自动化会话。会话冲突会破坏你的工作流程...

📹 演示视频：

🚀 使用 Playwright Plus MCP

🎯 游戏规则改变者：同时打开多个浏览器进行并发自动化测试！
体验并行浏览器自动化的强大力量 - 同时在不同项目中运行多个自动化测试，每个都有自己的持久会话！

📹 演示视频：

💡 注意： 这些视频展示了革命性的差异 - 从单浏览器限制到无限并发浏览器自动化。

🔥 你刚刚见证的：

😫 修复前： 只能一个浏览器。打开新项目 = 会话被销毁。每次都要手动重新登录。
🚀 修复后： 无限并发浏览器！ 同时打开 5、10、20+ 个浏览器自动化会话。每个项目都保持自己的持久状态。真正的大规模并行自动化测试！

Playwright MCP Plus

一个增强版的模型上下文协议（MCP）服务器，使用 Playwright 提供浏览器自动化功能。

🎯 核心创新：项目级会话隔离

⚡ 我们解决的问题：

单浏览器瓶颈： 常规 Playwright MCP = 一次只能运行一个浏览器自动化会话
打开多个项目窗口会导致灾难性的会话冲突
每个新的自动化任务都会销毁之前的浏览器会话
自动化测试在规模化时变得不可能 - 你无法运行并行测试
持续的重新认证会扼杀生产力并破坏 CI/CD 工作流程

🚀 我们的革命性解决方案： 🎯 无限并发浏览器自动化 - 在不同项目中同时运行多个自动化测试，每个都有隔离的持久会话！

✨ 这为你解锁了什么：

🚀 并发自动化测试 - 同时运行 10+ 个浏览器自动化会话而不冲突
🔄 再也不会丢失登录状态 - 每个项目都维护自己的认证会话
🪟 并行项目工作流 - 同时在多个项目中自动化测试
🧪 可扩展的测试自动化 - 你的测试套件并行运行，更快更可靠
💾 会话在 IDE 重启后持久保存 - 关闭并重新打开项目，所有会话仍然完好
🎯 零配置要求 - 开箱即用，具有智能默认设置

🚀 增强功能（相比官方 Playwright MCP）

这个增强版本保持与官方 Playwright MCP 100% 向后兼容，同时解锁无限并发浏览器自动化：

🎯 并发自动化测试

🚀 无限并行浏览器：同时运行多个浏览器自动化会话而不冲突
⚡ 可扩展测试自动化：在多个项目中并发执行自动化测试
🔄 零会话干扰：每个浏览器会话完全与其他会话隔离

🔒 项目会话隔离

🏗️ 自动项目检测：每个项目都有自己的隔离浏览器会话
💾 持久登录状态：在 IDE 重启和窗口切换时保持登录状态
🚪 不再重新认证：你的自动化测试和工作流程不间断运行
📁 清洁项目目录：默认情况下项目文件夹中没有会话文件
🌍 跨平台支持：为 Windows、macOS、Linux 智能选择存储位置

🛠️ 多种存储策略

system：存储在操作系统缓存目录（推荐，用户不可见）
project：存储在项目目录（传统行为）
custom：存储在自定义位置

⚙️ 配置参数

--project-isolation：启用项目级会话隔离（默认：禁用）
--project-isolation-session-strategy：选择存储策略（默认："system"）
--project-isolation-session-root-dir：会话存储的自定义根目录

✅ 相比官方版本的革命性优势

🚀 无限并发浏览器：同时运行多个浏览器自动化会话（相比单会话限制）
⚡ 并行自动化测试：同时在多个项目中执行自动化测试
✅ 100% 向后兼容：官方版本的直接替代品
✅ 多项目工作流：在多个项目上工作而不会话冲突
✅ 持久认证：会话之间永不丢失登录状态
✅ 可扩展测试自动化：消除重新登录开销并启用并行测试执行
✅ 清洁工作空间：默认情况下项目目录中没有会话文件
✅ 无冲突：使用官方 Playwright 路径结构避免冲突
✅ 零维护：自动清理和管理会话数据

核心功能

🚀 并发浏览器自动化。运行无限并行浏览器会话进行可扩展的自动化测试。
🧩 Chrome 扩展管理。以编程方式安装、卸载和管理 Chrome 扩展，支持自动浏览器重启。
快速轻量。使用 Playwright 的可访问性树，而不是基于像素的输入。
LLM 友好。不需要视觉模型，纯粹基于结构化数据操作。
确定性工具应用。避免基于截图方法常见的歧义。
🆕 项目级隔离。每个项目都有独立的浏览器会话和智能存储管理。

要求

Node.js 18 或更新版本
VS Code、Cursor、Windsurf、Claude Desktop、Goose 或任何其他 MCP 客户端

开始使用

首先，在你的客户端中安装 Playwright MCP 服务器。

标准配置（与官方 Playwright MCP 100% 兼容）：

{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "-y",
        "@ai-coding-labs/playwright-mcp-plus@latest"
      ]
    }
  }
}

增强配置，带项目隔离（推荐）：

{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "-y",
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation"
      ]
    }
  }
}

高级配置，带自定义会话存储：

{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "-y",
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation",
        "--project-isolation-session-strategy=custom",
        "--project-isolation-session-root-dir=/custom/session/path"
      ]
    }
  }
}

💡 多项目工作流专业提示：

一旦启用 --project-isolation，你的每个项目都会自动获得自己的浏览器会话。当你调用任何浏览器工具时，只需包含项目参数：

// 每个项目自动获得隔离的会话
browser_navigate({
  url: "https://yourapp.com",
  projectDrive: "/",                    // macOS/Linux: "/"，Windows: "C:"
  projectPath: "/path/to/your/project"  // 项目目录的绝对路径
})

这确保你的登录状态、cookies 和浏览器数据在不同项目之间永不干扰！

🎬 真实世界使用场景

修复前（官方 Playwright MCP）：

# 在项目 A 上工作 - 登录管理面板
browser_navigate("https://myapp-staging.com/admin")
# 用凭据登录，做一些测试...

# 切换到项目 B 窗口 - 会话丢失！😱
browser_navigate("https://different-app.com/dashboard")
# 项目 A 的所有登录状态都消失了，必须重新登录

# 切换回项目 A - 登录又丢失了！😱
# 每次都必须重新认证

修复后（带项目隔离）：

# 项目 A - 登录一次，永远保持登录
browser_navigate({
  url: "https://myapp-staging.com/admin",
  projectDrive: "/",
  projectPath: "/Users/you/projects/project-a"
})

# 项目 B - 完全独立的会话
browser_navigate({
  url: "https://different-app.com/dashboard",
  projectDrive: "/",
  projectPath: "/Users/you/projects/project-b"
})

# 切换回项目 A - 仍然登录！✨
# 无需重新认证，会话完美保存

结果： 你的自动化测试运行速度提高 10 倍，开发工作流程不被中断，你可以同时在多个项目上工作而不会丢失认证状态。

🧩 Chrome 扩展管理

Playwright MCP Plus 包含强大的 Chrome 扩展管理功能，允许你以编程方式安装、卸载和管理 Chrome 扩展，并支持自动浏览器重启以立即生效。

核心功能：

🚀 一键安装：直接从 Chrome 网上应用店 URL 或扩展 ID 安装扩展
🔄 自动浏览器重启：安装后扩展立即可用
🗑️ 干净卸载：完全移除扩展并自动清理
📋 扩展注册表：跟踪所有已安装扩展的详细信息
🏠 本地管理：扩展存储在本地 ~/.mcp-extensions/ 目录中

使用示例：

// 通过 URL 安装扩展并立即加载
browser_extension_install({
  extensionUrl: "https://chromewebstore.google.com/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa",
  loadImmediately: true,
  projectDrive: "/",
  projectPath: "/path/to/your/project"
})

// 通过 ID 安装扩展
browser_extension_install({
  extensionId: "chklaanhfefbnpoihckbnefhakgolnmc",
  loadImmediately: true
})

// 列出所有已安装的扩展
browser_extension_list()

// 卸载扩展并立即生效
browser_extension_uninstall({
  extensionId: "bcjindcccaagfpapjjmafapmmgkkhgoa",
  restartImmediately: true
})

完美适用于：

🧪 自动化测试：为测试套件安装测试扩展
🛠️ 开发工作流：快速设置带有所需扩展的开发环境
🔧 CI/CD 流水线：在自动化工作流中以编程方式管理浏览器扩展
📊 网页抓取：安装增强数据提取能力的扩展

使用 Claude Code CLI 添加增强版 Playwright MCP 服务器：

标准版本：

claude mcp add playwright-plus npx -y @ai-coding-labs/playwright-mcp-plus@latest

带项目隔离（推荐）：

claude mcp add playwright-plus npx -y @ai-coding-labs/playwright-mcp-plus@latest --project-isolation

按照 MCP 安装指南，使用上面的标准配置。

点击按钮安装：

或手动安装：

转到 Cursor Settings -> MCP -> Add new MCP Server。随意命名，使用 command 类型，命令为 npx -y @ai-coding-labs/playwright-mcp-plus --project-isolation。你也可以通过点击 Edit 验证配置或添加命令参数。

按照 MCP 安装指南，使用上面的标准配置。

点击按钮安装：

或手动安装：

转到 Advanced settings -> Extensions -> Add custom extension。随意命名，使用类型 STDIO，将 command 设置为 npx -y @ai-coding-labs/playwright-mcp-plus --project-isolation。点击 "Add Extension"。

点击按钮安装：

或手动安装：

转到右侧边栏的 Program -> Install -> Edit mcp.json。使用上面的标准配置。

在 VSCode 或 IntelliJ 中打开 Qodo Gen 聊天面板 → Connect more tools → + Add new MCP → 粘贴上面的标准配置。

点击 Save。

点击按钮安装：

或手动安装：

按照 MCP 安装指南，使用上面的标准配置。你也可以使用 VS Code CLI 安装 Playwright MCP 服务器：

# 对于 VS Code
code --add-mcp '{"name":"playwright-plus","command":"npx","args":["-y","@ai-coding-labs/playwright-mcp-plus@latest","--project-isolation"]}'

安装后，Playwright MCP 服务器将可用于 VS Code 中的 GitHub Copilot 代理。

按照 Windsurf MCP 文档。使用上面的标准配置。

配置

Playwright MCP 服务器支持以下参数。它们可以在上面的 JSON 配置中作为 "args" 列表的一部分提供：

> npx @ai-coding-labs/playwright-mcp-plus@latest --help
  --allowed-origins <origins>                      允许浏览器请求的源的分号分隔列表。默认允许所有。
  --blocked-origins <origins>                      阻止浏览器请求的源的分号分隔列表。阻止列表在允许列表之前评估。如果在没有允许列表的情况下使用，不匹配阻止列表的请求仍然被允许。
  --block-service-workers                          阻止 service workers
  --browser <browser>                              要使用的浏览器或 chrome 频道，可能的值：chrome、firefox、webkit、msedge。
  --caps <caps>                                    要启用的附加功能的逗号分隔列表，可能的值：vision、pdf。
  --cdp-endpoint <endpoint>                        要连接的 CDP 端点。
  --config <path>                                  配置文件的路径。
  --device <device>                                要模拟的设备，例如："iPhone 15"
  --executable-path <path>                         浏览器可执行文件的路径。
  --headless                                       在无头模式下运行浏览器，默认有头
  --host <host>                                    绑定服务器的主机。默认是 localhost。使用 0.0.0.0 绑定到所有接口。
  --ignore-https-errors                            忽略 https 错误
  --isolated                                       将浏览器配置文件保存在内存中，不保存到磁盘。
  --image-responses <mode>                         是否向客户端发送图像响应。可以是 "allow" 或 "omit"，默认为 "allow"。
  --no-sandbox                                     为通常沙盒化的所有进程类型禁用沙盒。
  --output-dir <path>                              输出文件目录的路径。
  --port <port>                                    SSE 传输监听的端口。
  --project-isolation                              使用来自 MCP 上下文的项目路径启用项目级会话隔离。
  --project-isolation-session-strategy <strategy>  项目隔离的会话目录策略：system、project、custom。默认为 "system"。(default: "system")
  --project-isolation-session-root-dir <path>      使用项目隔离时会话存储的自定义根目录（仅在 --project-isolation-session-strategy=custom 时使用）。
  --proxy-bypass <bypass>                          绕过代理的逗号分隔域，例如 ".com,chromium.org,.domain.com"
  --proxy-server <proxy>                           指定代理服务器，例如 "http://myproxy:3128" 或 "socks5://myproxy:8080"
  --save-session                                   是否将 Playwright MCP 会话保存到输出目录。
  --save-trace                                     是否将会话的 Playwright Trace 保存到输出目录。
  --storage-state <path>                           隔离会话的存储状态文件路径。
  --user-agent <ua string>                         指定用户代理字符串
  --user-data-dir <path>                           用户数据目录的路径。如果未指定，将创建临时目录。
  --viewport-size <size>                           指定浏览器视口大小（像素），例如 "1280, 720"

用户配置文件

你可以像常规浏览器一样使用持久配置文件运行 Playwright MCP（默认），或在隔离上下文中进行测试会话。

持久配置文件

所有登录信息都将存储在持久配置文件中，如果你想清除离线状态，可以在会话之间删除它。持久配置文件位于以下位置，你可以使用 --user-data-dir 参数覆盖它。

# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile

# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile

# Linux
- ~/.cache/ms-playwright/mcp-{channel}-profile

隔离

在隔离模式下，每个会话都在隔离配置文件中启动。每次你要求 MCP 关闭浏览器时，会话都会关闭，此会话的所有存储状态都会丢失。你可以通过配置的 contextOptions 或通过 --storage-state 参数向浏览器提供初始存储状态。在这里了解更多关于存储状态的信息。

{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--isolated",
        "--storage-state={path/to/storage.json}"
      ]
    }
  }
}

🔒 项目隔离（增强功能）

项目隔离允许每个项目维护自己独立的浏览器会话，具有独立的登录状态、cookies 和 localStorage。这可以防止跨项目干扰，同时保持工作空间清洁。

默认行为（向后兼容）

没有任何隔离标志时，会话在所有项目之间共享（与官方 Playwright MCP 相同）：

{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": ["@ai-coding-labs/playwright-mcp-plus@latest"]
    }
  }
}

推荐：系统策略（零配置）

启用项目隔离，会话存储在操作系统缓存目录中（对用户不可见）：

{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation"
      ]
    }
  }
}

按操作系统的存储位置：

Windows: %LOCALAPPDATA%/ms-playwright/mcp-chrome-profile/playwright-plus-mcp/project-hash/
macOS: ~/Library/Caches/ms-playwright/mcp-chrome-profile/playwright-plus-mcp/project-hash/
Linux: ~/.cache/ms-playwright/mcp-chrome-profile/playwright-plus-mcp/project-hash/

项目策略

在项目目录中存储会话（创建 .user-session-data-directory/）：

{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation",
        "--project-isolation-session-strategy=project"
      ]
    }
  }
}

自定义策略

在自定义位置存储会话：

{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation",
        "--project-isolation-session-strategy=custom",
        "--project-isolation-session-root-dir=/custom/sessions"
      ]
    }
  }
}

策略比较

| 配置 | 会话位置 | 项目目录 | 用户可见性 | 使用场景 | |------|----------|----------|------------|----------| | 无隔离（默认） | 共享缓存 | 清洁 | 隐藏 | 向后兼容 | | 系统（隔离默认） | 操作系统缓存目录 | 清洁 | 隐藏 | 最佳用户体验 | | 项目 | .user-session-data-directory/ | 有会话文件 | 可见 | 传统/调试 | | 自定义 | 自定义路径 | 清洁 | 隐藏 | 高级设置 |

配置文件

Playwright MCP 服务器可以使用 JSON 配置文件进行配置。你可以使用 --config 命令行选项指定配置文件：

npx @ai-coding-labs/playwright-mcp-plus@latest --config path/to/config.json

{
  // 浏览器配置
  browser?: {
    // 要使用的浏览器类型（chromium、firefox 或 webkit）
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // 将浏览器配置文件保存在内存中，不保存到磁盘。
    isolated?: boolean;

    // 浏览器配置文件持久化的用户数据目录路径
    userDataDir?: string;

    // 浏览器启动选项（参见 Playwright 文档）
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // 浏览器频道（例如 'chrome'）
      headless?: boolean;      // 在无头模式下运行
      executablePath?: string; // 浏览器可执行文件路径
      // ... 其他 Playwright 启动选项
    };

    // 浏览器上下文选项
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... 其他 Playwright 上下文选项
    };

    // 用于连接到现有浏览器的 CDP 端点
    cdpEndpoint?: string;

    // 远程 Playwright 服务器端点
    remoteEndpoint?: string;
  },

  // 服务器配置
  server?: {
    port?: number;  // 监听端口
    host?: string;  // 绑定主机（默认：localhost）
  },

  // 附加功能列表
  capabilities?: Array<
    'tabs' |    // 标签管理
    'install' | // 浏览器安装
    'pdf' |     // PDF 生成
    'vision' |  // 基于坐标的交互
  >;

  // 输出文件目录
  outputDir?: string;

  // 网络配置
  network?: {
    // 允许浏览器请求的源列表。默认允许所有。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
    allowedOrigins?: string[];

    // 阻止浏览器请求的源列表。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
    blockedOrigins?: string[];
  };

  /**
   * 是否向客户端发送图像响应。可以是 "allow" 或 "omit"。
   * 默认为 "allow"。
   */
  imageResponses?: 'allow' | 'omit';

  /**
   * 使用来自 MCP 上下文的项目路径启用项目级会话隔离。
   * 启用时，每个项目都有自己的隔离浏览器会话。
   * 默认为 false（共享会话，与官方 Playwright MCP 兼容）。
   */
  projectIsolation?: boolean;

  /**
   * 项目隔离的会话目录存储策略。
   * 仅在启用 projectIsolation 时使用。
   * - 'system'：存储在操作系统缓存目录（推荐，用户不可见）
   * - 'project'：存储在项目目录（传统行为）
   * - 'custom'：存储在 projectIsolationSessionRootDir 指定的自定义位置
   * 默认为 "system"。
   */
  projectIsolationSessionStrategy?: 'system' | 'project' | 'custom';

  /**
   * 使用项目隔离时会话存储的自定义根目录。
   * 仅在 projectIsolationSessionStrategy 为 'custom' 时使用。
   * 示例："/custom/session/storage/path"
   */
  projectIsolationSessionRootDir?: string;
}

独立 MCP 服务器

在没有显示器的系统上运行有头浏览器或从 IDE 的工作进程运行时，从具有 DISPLAY 的环境运行 MCP 服务器并传递 --port 标志以启用 HTTP 传输。

npx @ai-coding-labs/playwright-mcp-plus@latest --port 8931

然后在 MCP 客户端配置中，将 url 设置为 HTTP 端点：

{
  "mcpServers": {
    "playwright-plus": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

注意： Docker 实现目前仅支持无头 chromium。

{
  "mcpServers": {
    "playwright-plus": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

你可以自己构建 Docker 镜像。

docker build -t mcr.microsoft.com/playwright/mcp .

import http from 'http';

import { createConnection } from '@ai-coding-labs/playwright-mcp-plus';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // 创建带有 SSE 传输的无头 Playwright MCP 服务器
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.sever.connect(transport);

  // ...
});

工具

browser_click
- 标题：点击
- 描述：在网页上执行点击操作
- 参数：
  - element (string)：用于获得与元素交互权限的人类可读元素描述
  - ref (string)：来自页面快照的确切目标元素引用
  - doubleClick (boolean, 可选)：是否执行双击而不是单击
  - button (string, 可选)：要点击的按钮，默认为左键
- 只读：false

browser_close
- 标题：关闭浏览器
- 描述：关闭页面
- 参数：
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：true

browser_console_messages
- 标题：获取控制台消息
- 描述：返回所有控制台消息
- 参数：无
- 只读：true

browser_drag
- 标题：拖拽鼠标
- 描述：在两个元素之间执行拖放操作
- 参数：
  - startElement (string)：用于获得与元素交互权限的人类可读源元素描述
  - startRef (string)：来自页面快照的确切源元素引用
  - endElement (string)：用于获得与元素交互权限的人类可读目标元素描述
  - endRef (string)：来自页面快照的确切目标元素引用
- 只读：false

browser_evaluate
- 标题：执行 JavaScript
- 描述：在页面或元素上执行 JavaScript 表达式
- 参数：
  - function (string)：() => { /* 代码 / } 或当提供元素时 (element) => { / 代码 */ }
  - element (string, 可选)：用于获得与元素交互权限的人类可读元素描述
  - ref (string, 可选)：来自页面快照的确切目标元素引用
- 只读：false

browser_file_upload
- 标题：上传文件
- 描述：上传一个或多个文件
- 参数：
  - paths (array)：要上传的文件的绝对路径。可以是单个文件或多个文件。
- 只读：false

browser_handle_dialog
- 标题：处理对话框
- 描述：处理对话框
- 参数：
  - accept (boolean)：是否接受对话框。
  - promptText (string, 可选)：在提示对话框情况下的提示文本。
- 只读：false

browser_hover
- 标题：悬停鼠标
- 描述：在页面上悬停在元素上
- 参数：
  - element (string)：用于获得与元素交互权限的人类可读元素描述
  - ref (string)：来自页面快照的确切目标元素引用
- 只读：true

browser_navigate
- 标题：导航到 URL
- 描述：导航到 URL
- 参数：
  - url (string)：要导航到的 URL
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：false

browser_navigate_back
- 标题：后退
- 描述：返回到上一页
- 参数：无
- 只读：true

browser_navigate_forward
- 标题：前进
- 描述：前进到下一页
- 参数：无
- 只读：true

browser_network_requests
- 标题：列出网络请求
- 描述：返回自加载页面以来的所有网络请求
- 参数：无
- 只读：true

browser_press_key
- 标题：按键
- 描述：在键盘上按键
- 参数：
  - key (string)：要按的键的名称或要生成的字符，例如 ArrowLeft 或 a
- 只读：false

browser_resize
- 标题：调整浏览器窗口大小
- 描述：调整浏览器窗口大小
- 参数：
  - width (number)：浏览器窗口的宽度
  - height (number)：浏览器窗口的高度
- 只读：true

browser_select_option
- 标题：选择选项
- 描述：在下拉菜单中选择选项
- 参数：
  - element (string)：用于获得与元素交互权限的人类可读元素描述
  - ref (string)：来自页面快照的确切目标元素引用
  - values (array)：在下拉菜单中选择的值数组。可以是单个值或多个值。
- 只读：false

browser_snapshot
- 标题：页面快照
- 描述：捕获当前页面的可访问性快照，这比截图更好
- 参数：
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：true

browser_take_screenshot
- 标题：截图
- 描述：对当前页面进行截图。你不能基于截图执行操作，请使用 browser_snapshot 进行操作。
- 参数：
  - type (string, 可选)：截图的图像格式。默认为 png。
  - filename (string, 可选)：保存截图的文件名。如果未指定，默认为 page-{timestamp}.{png|jpeg}。
  - element (string, 可选)：用于获得截图元素权限的人类可读元素描述。如果未提供，将截取视口。如果提供了 element，也必须提供 ref。
  - ref (string, 可选)：来自页面快照的确切目标元素引用。如果未提供，将截取视口。如果提供了 ref，也必须提供 element。
  - fullPage (boolean, 可选)：当为 true 时，截取完整可滚动页面的截图，而不是当前可见的视口。不能与元素截图一起使用。
- 只读：true

browser_type
- 标题：输入文本
- 描述：在可编辑元素中输入文本
- 参数：
  - element (string)：用于获得与元素交互权限的人类可读元素描述
  - ref (string)：来自页面快照的确切目标元素引用
  - text (string)：要输入到元素中的文本
  - submit (boolean, 可选)：是否提交输入的文本（之后按 Enter）
  - slowly (boolean, 可选)：是否一次输入一个字符。对于触发页面中的键处理程序很有用。默认情况下，整个文本一次性填入。
- 只读：false

browser_wait_for
- 标题：等待
- 描述：等待文本出现或消失或指定时间过去
- 参数：
  - time (number, 可选)：等待的时间（秒）
  - text (string, 可选)：要等待的文本
  - textGone (string, 可选)：要等待消失的文本
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：true

browser_tab_close
- 标题：关闭标签
- 描述：关闭标签
- 参数：
  - index (number, 可选)：要关闭的标签的索引。如果未提供，则关闭当前标签。
- 只读：false

browser_tab_list
- 标题：列出标签
- 描述：列出浏览器标签
- 参数：
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：true

browser_tab_new
- 标题：打开新标签
- 描述：打开新标签
- 参数：
  - url (string, 可选)：在新标签中导航到的 URL。如果未提供，新标签将为空白。
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：true

browser_tab_select
- 标题：选择标签
- 描述：按索引选择标签
- 参数：
  - index (number)：要选择的标签的索引
- 只读：true

browser_install
- 标题：安装配置中指定的浏览器
- 描述：安装配置中指定的浏览器。如果你收到关于浏览器未安装的错误，请调用此功能。
- 参数：
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：false

browser_mouse_click_xy
- 标题：点击
- 描述：在给定位置点击鼠标左键
- 参数：
  - element (string)：用于获得与元素交互权限的人类可读元素描述
  - x (number)：X 坐标
  - y (number)：Y 坐标
- 只读：false

browser_mouse_drag_xy
- 标题：拖拽鼠标
- 描述：将鼠标左键拖拽到给定位置
- 参数：
  - element (string)：用于获得与元素交互权限的人类可读元素描述
  - startX (number)：起始 X 坐标
  - startY (number)：起始 Y 坐标
  - endX (number)：结束 X 坐标
  - endY (number)：结束 Y 坐标
- 只读：false

browser_mouse_move_xy
- 标题：移动鼠标
- 描述：将鼠标移动到给定位置
- 参数：
  - element (string)：用于获得与元素交互权限的人类可读元素描述
  - x (number)：X 坐标
  - y (number)：Y 坐标
- 只读：true

browser_extension_install
- 标题：安装 Chrome 扩展
- 描述：通过下载并本地管理从 Chrome 网上应用店安装 Chrome 扩展
- 参数：
  - extensionId (string, 可选)：Chrome 扩展 ID（例如，"cjpalhdlnbpafiamejdnhcphjbkeiagm"）
  - extensionUrl (string, 可选)：扩展的完整 Chrome 网上应用店 URL
  - waitForInstall (boolean, 可选)：是否等待安装完成（默认：true）
  - loadImmediately (boolean, 可选)：是否重启浏览器以立即加载扩展（默认：true）
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：false

browser_extension_uninstall
- 标题：卸载 Chrome 扩展
- 描述：从 MCP 管理中卸载 Chrome 扩展并重启浏览器
- 参数：
  - extensionId (string)：要卸载的 Chrome 扩展 ID（例如，"bcjindcccaagfpapjjmafapmmgkkhgoa"）
  - restartImmediately (boolean, 可选)：是否在卸载后立即重启浏览器（默认：true）
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：false

browser_extension_list
- 标题：列出已安装的扩展
- 描述：列出所有 MCP 管理的 Chrome 扩展
- 参数：
  - projectDrive (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
  - projectPath (string, 可选)：用于会话隔离的项目根目录的绝对路径
- 只读：true

browser_pdf_save
- 标题：保存为 PDF
- 描述：将页面保存为 PDF
- 参数：
  - filename (string, 可选)：保存 PDF 的文件名。如果未指定，默认为 page-{timestamp}.pdf。
- 只读：true

配置文件

Playwright MCP 服务器可以使用 JSON 配置文件进行配置。你可以使用 --config 命令行选项指定配置文件：

npx @ai-coding-labs/playwright-mcp-plus@latest --config path/to/config.json

{
  // 浏览器配置
  browser?: {
    // 要使用的浏览器类型（chromium、firefox 或 webkit）
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // 将浏览器配置文件保存在内存中，不保存到磁盘。
    isolated?: boolean;

    // 浏览器配置文件持久化的用户数据目录路径
    userDataDir?: string;

    // 浏览器启动选项（参见 Playwright 文档）
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // 浏览器频道（例如 'chrome'）
      headless?: boolean;      // 在无头模式下运行
      executablePath?: string; // 浏览器可执行文件路径
      // ... 其他 Playwright 启动选项
    };

    // 浏览器上下文选项
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... 其他 Playwright 上下文选项
    };

    // 用于连接到现有浏览器的 CDP 端点
    cdpEndpoint?: string;

    // 远程 Playwright 服务器端点
    remoteEndpoint?: string;
  },

  // 服务器配置
  server?: {
    port?: number;  // 监听端口
    host?: string;  // 绑定主机（默认：localhost）
  },

  // 附加功能列表
  capabilities?: Array<
    'tabs' |    // 标签管理
    'install' | // 浏览器安装
    'pdf' |     // PDF 生成
    'vision' |  // 基于坐标的交互
  >;

  // 输出文件目录
  outputDir?: string;

  // 网络配置
  network?: {
    // 允许浏览器请求的源列表。默认允许所有。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
    allowedOrigins?: string[];

    // 阻止浏览器请求的源列表。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
    blockedOrigins?: string[];
  };

  /**
   * 是否向客户端发送图像响应。可以是 "allow" 或 "omit"。
   * 默认为 "allow"。
   */
  imageResponses?: 'allow' | 'omit';

  /**
   * 使用来自 MCP 上下文的项目路径启用项目级会话隔离。
   * 启用时，每个项目都有自己的隔离浏览器会话。
   * 默认为 false（共享会话，与官方 Playwright MCP 兼容）。
   */
  projectIsolation?: boolean;

  /**
   * 项目隔离的会话目录存储策略。
   * 仅在启用 projectIsolation 时使用。
   * - 'system'：存储在操作系统缓存目录（推荐，用户不可见）
   * - 'project'：存储在项目目录（传统行为）
   * - 'custom'：存储在 projectIsolationSessionRootDir 指定的自定义位置
   * 默认为 "system"。
   */
  projectIsolationSessionStrategy?: 'system' | 'project' | 'custom';

  /**
   * 使用项目隔离时会话存储的自定义根目录。
   * 仅在 projectIsolationSessionStrategy 为 'custom' 时使用。
   * 示例："/custom/session/storage/path"
   */
  projectIsolationSessionRootDir?: string;
}

独立 MCP 服务器

在没有显示器的系统上运行有头浏览器或从 IDE 的工作进程运行时，从具有 DISPLAY 的环境运行 MCP 服务器并传递 --port 标志以启用 HTTP 传输。

npx @ai-coding-labs/playwright-mcp-plus@latest --port 8931

然后在 MCP 客户端配置中，将 url 设置为 HTTP 端点：

{
  "mcpServers": {
    "playwright-plus": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

注意： Docker 实现目前仅支持无头 chromium。

{
  "mcpServers": {
    "playwright-plus": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

你可以自己构建 Docker 镜像。

docker build -t mcr.microsoft.com/playwright/mcp .

import http from 'http';

import { createConnection } from '@ai-coding-labs/playwright-mcp-plus';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // 创建带有 SSE 传输的无头 Playwright MCP 服务器
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.sever.connect(transport);

  // ...
});

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Playwright MCP Plus

🎭 看看区别！

😫 没有 Playwright Plus MCP

🚀 使用 Playwright Plus MCP

Playwright MCP Plus

🎯 核心创新：项目级会话隔离

🚀 增强功能（相比官方 Playwright MCP）

🎯 并发自动化测试

🔒 项目会话隔离

🛠️ 多种存储策略

⚙️ 配置参数

✅ 相比官方版本的革命性优势

核心功能

要求

开始使用

🎬 真实世界使用场景

🧩 Chrome 扩展管理

点击按钮安装：

或手动安装：

点击按钮安装：

或手动安装：

点击按钮安装：

或手动安装：

点击按钮安装：

或手动安装：

配置

用户配置文件

🔒 项目隔离（增强功能）

默认行为（向后兼容）

推荐：系统策略（零配置）

项目策略

自定义策略

策略比较

配置文件

独立 MCP 服务器

工具

配置文件

独立 MCP 服务器