项目概述

Playwright MCP（Model Context Protocol）是一个为 MCP（Model Context Protocol）协议提供 Playwright 工具的官方实现。该项目由 Microsoft 开发维护，为大语言模型（LLM）代理提供浏览器自动化能力，使其能够与网页进行交互、操作 DOM 元素、执行网络请求等操作。

Playwright MCP 作为 MCP 服务器运行，通过标准输入输出（stdio）传输协议与 MCP 客户端通信 资料来源：server.json:1-13。

核心特性

架构设计

系统架构

graph TD
    A[MCP 客户端] -->|stdio| B[Playwright MCP 服务器]
    B --> C[Playwright Core]
    C --> D[Chromium]
    C --> E[Firefox]
    C --> F[WebKit]
    B --> G[工具注册表]
    G --> H[Core 工具]
    G --> I[Navigation 工具]
    G --> J[Input 工具]
    G --> K[Network 工具]
    G --> L[Testing 工具]
    G --> M[Vision 工具]

源码位置

[!WARNING]

Playwright MCP 的核心代码已迁移至 Playwright 主仓库。当前仓库主要用于打包和发布。

核心源码位于 packages/playwright/src/mcp 目录下 资料来源：CONTRIBUTING.md:1-20。

模块导出

主入口文件通过 playwright-core/lib/coreBundle 导出 createConnection 函数：

const { tools } = require('playwright-core/lib/coreBundle');
module.exports = { createConnection: tools.createConnection };

资料来源：index.js:1-24

工具能力体系

Playwright MCP 将功能组织为多个能力（Capability）模块，每个模块提供一组相关的 MCP 工具。

能力类型定义

export type ToolCapability =
  'config' |        // 配置管理
  'core' |          // 核心功能
  'core-navigation' | // 导航功能
  'core-tabs' |     // 标签页管理
  'core-input' |    // 输入操作
  'core-install' |  // 安装功能
  'network' |       // 网络请求
  'pdf' |           // PDF 生成
  'storage' |       // 存储管理
  'testing' |       // 测试功能
  'vision' |        // 视觉功能
  'devtools';       // 开发者工具

资料来源：config.d.ts:1-20

工具注册机制

工具信息通过 update-readme.js 脚本从编译后的模块中提取，并自动生成 README 文档：

async function updateTools(content) {
  console.log('Loading tool information from compiled modules...');
  // 按能力分组列出工具
  for (const [capability, tools] of Object.entries(toolsByCapability)) {
    generatedLines.push(`

# Playwright MCP vs Playwright CLI

## 概述

Playwright MCP (Model Context Protocol) 和 Playwright CLI 是 Playwright 生态系统中的两个不同入口点，它们服务于不同的使用场景和集成模式。

**Playwright MCP** 是一个基于 Model Context Protocol 的服务器实现，允许 AI 模型通过标准化的 MCP 协议与 Playwright 浏览器自动化功能进行交互。它以 npm 包 `@playwright/mcp` 的形式发布，版本为 `0.0.75`，MCP 名称为 `io.github.microsoft/playwright-mcp` 资料来源：[package.json:1-20]()

**Playwright CLI** 是传统的命令行工具，通过终端命令直接调用 Playwright 的各项功能，如启动浏览器、安装浏览器、执行测试等。资料来源：[cli.js:1-35]()

> **重要说明**：Playwright MCP 的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md:1-10]()

概述

Playwright MCP（Model Context Protocol）是由微软开发的Playwright工具集，通过MCP协议为大型语言模型提供浏览器自动化能力。该项目允许AI代理通过标准化的工具接口执行网页导航、元素交互、截图捕获等浏览器操作。资料来源：README.md

[!IMPORTANT]

Playwright MCP的核心代码已迁移至 Playwright 主仓库，源代码位于 packages/playwright/src/mcp 目录。资料来源：CONTRIBUTING.md

环境要求

安装步骤

1. 克隆仓库

由于核心代码已迁移至Playwright主仓库，推荐从主仓库克隆：

git clone https://github.com/microsoft/playwright
cd playwright

资料来源：CONTRIBUTING.md

2. 安装依赖并构建

# 安装项目依赖
npm ci

# 以监视模式运行构建
npm run watch

# 安装浏览器（根据需要选择）
npx playwright install

3. 验证安装

运行快速测试验证安装是否成功：

# 仅在Chromium中运行MCP测试（快速路径）
npm run mcp-ctest

# 在三个浏览器中运行完整测试（慢速路径）
npm run mcp-test

项目结构

playwright/
├── packages/
│   └── playwright/
│       └── src/
│           └── mcp/          # MCP核心源代码
├── tests/
│   └── mcp/                  # MCP测试套件
├── config.d.ts               # 配置类型定义
├── playwright.config.ts     # 测试配置
└── package.json             # 项目配置

可用工具分类

Playwright MCP提供以下能力类别：

资料来源：config.d.ts

配置选项

浏览器配置

{
  browser: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;        // 是否保持浏览器配置在内存中
    userDataDir?: string;      // 用户数据目录路径
  };
}

超时配置

{
  timeouts: {
    action?: number;      // 默认操作超时，默认5000ms
    navigation?: number;  // 默认导航超时，默认60000ms
    expect?: number;      // 默认expect超时，默认5000ms
  };
}

网络配置

{
  network: {
    allowedOrigins?: string[];   // 允许的请求来源
    blockedOrigins?: string[];   // 阻止的请求来源
  };
}

资料来源：config.d.ts

命令行工具

项目提供以下npm脚本命令：

资料来源：package.json

直接使用CLI

# 启动MCP服务器
node index.js

# 安装浏览器
node cli.js install-browser

# 获取帮助
node cli.js --help

资料来源：cli.js，index.js

测试运行流程

graph TD
    A[开始测试] --> B{环境变量CI}
    B -->|是| C[设置2个workers]
    B -->|否| D[使用全部CPU核心]
    C --> E[运行playwright test]
    D --> E
    E --> F{测试结果}
    F -->|通过| G[测试完成]
    F -->|失败| H[报告错误]

开发工作流

提交规范

项目使用语义化提交信息格式：

label(namespace): 标题

描述

footer

可用标签：

资料来源：CONTRIBUTING.md

分支命名

• 错误修复：fix-<issue-number>
• Playwright版本滚动：roll-pw-<version-suffix>

代码规范

• 代码风格定义在 eslint.config.mjs
• 提交前运行代码检查：npm run flint
• 注释应有明确目的，避免冗余
• 代码应尽可能自解释

资料来源：CONTRIBUTING.md

常见问题

Q: 测试无法通过怎么办？

1. 确保所有依赖已正确安装：npm ci
2. 确保浏览器已安装：npx playwright install
3. 清除缓存后重试

Q: 如何仅测试特定浏览器？

# 仅Chrome
npm run ctest

# 仅Firefox
npm run ftest

# 仅WebKit
npm run wtest

Q: 如何在Docker中运行测试？

MCP_IN_DOCKER=1 npm run dtest

下一步

• 阅读完整 README.md 了解所有可用工具
• 查看 tests/mcp 目录中的测试示例
• 参考 Playwright 官方文档 了解底层API

概述

Playwright MCP (Model Context Protocol) 是微软提供的 Playwright 浏览器自动化工具的 MCP（Model Context Protocol）实现。它允许 AI 模型通过标准化协议与浏览器进行交互，执行网页自动化、测试和内容抓取等任务。

核心代码已迁移至 Playwright 主仓库，位于 packages/playwright/src/mcp 目录。资料来源：CONTRIBUTING.md:43

架构概览

graph TD
    A[AI Client / MCP Host] -->|MCP Protocol| B[Playwright MCP Server]
    B -->|STDIO Transport| C[Browser Automation]
    C -->|Playwright API| D[Chromium / Firefox / WebKit]
    B --> E[Local Browser]
    B --> F[Docker Container]
    
    G[Config File / CLI Args] --> B
    H[Environment Variables] --> B

服务器通过 STDIO 传输协议与 MCP Host 进行通信，支持本地浏览器启动和 Docker 容器模式。资料来源：server.json:12

安装与依赖

系统要求

• Node.js: 需要版本 >= 18
• 浏览器: 支持 Chromium、Firefox、WebKit

安装步骤

npm install @playwright/mcp

或从源码构建：

git clone https://github.com/microsoft/playwright
cd playwright
npm ci
npm run watch
npx playwright install

资料来源：CONTRIBUTING.md:51-60

Docker 部署

# 构建镜像
npm run docker-build

# 运行容器
npm run docker-run

资料来源：package.json:25-27

配置选项

Playwright MCP 支持丰富的配置选项，定义在 config.d.ts 中。

配置类型定义

export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    // 浏览器启动选项
  };
  allowedOrigins?: string[];      // 允许的请求来源
  blockedOrigins?: string[];      // 阻止的请求来源
  testIdAttribute?: string;       // 测试 ID 属性，默认 "data-testid"
  timeouts?: {
    action?: number;              // 操作超时，默认 5000ms
    navigation?: number;         // 导航超时，默认 60000ms
    expect?: number;              // 断言超时，默认 5000ms
  };
  imageResponses?: 'allow' | 'omit' | 'auto';
};

资料来源：config.d.ts:31-85

工具能力列表

资料来源：config.d.ts:12-25

来源过滤配置

#### 允许来源 (allowedOrigins)

allowedOrigins?: string[];

支持的格式：

资料来源：config.d.ts:38-45

#### 阻止来源 (blockedOrigins)

blockedOrigins?: string[];

同时匹配 allowedOrigins 和 blockedOrigins 的来源将被阻止。

命令行接口

CLI 入口点

服务器通过 cli.js 启动，使用 playwright-core 的命令行框架：

node cli.js [options]

资料来源：cli.js:1-32

可用命令

主要选项

环境变量格式为 PLAYWRIGHT_MCP_ 前缀加上选项名称的大写形式，中划线替换为下划线。

资料来源：update-readme.js:1-60

特殊命令

#### install-browser

node cli.js install-browser

该命令实际上是 playwright install 的别名，用于安装必要的浏览器二进制文件。

工具能力详解

核心能力 (core)

默认启用的核心工具集，提供基础的浏览器操作能力：

网络能力 (network)

通过 --caps=network 启用，提供网络请求拦截和管理功能：

graph LR
    A[Browser Request] --> B{MCP Network Filter}
    B -->|Allowed| C[Network]
    B -->|Blocked| D[Blocked Response]

测试能力 (testing)

通过 --caps=testing 启用，提供测试断言功能：

• expect: 断言验证
• toHaveTitle: 标题验证
• toContainText: 文本内容验证
• toBeVisible: 元素可见性验证

资料来源：update-readme.js:70-100

环境变量

测试指南

运行测试

# 快速测试（仅 Chromium）
npm run ctest

# 完整测试（三浏览器）
npm run test

# Firefox 专项测试
npm run ftest

# WebKit 专项测试
npm run wtest

# Docker 模式测试
npm run dtest

资料来源：package.json:20-24

测试配置

测试配置文件位于 playwright.config.ts：

export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
  ],
});

测试文件位于 tests/mcp 目录。资料来源：playwright.config.ts:1-30

测试要求

• 测试必须是自包含的，不依赖外部服务
• 测试必须在三个平台都能运行：macOS、Linux、Windows
• 新功能必须包含对应的测试用例
• 纯重构可以例外

资料来源：CONTRIBUTING.md:90-95

集成示例

基本集成配置

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "env": {
        "PLAYWRIGHT_MCP_CAPS": "core,network",
        "PLAYWRIGHT_MCP_BROWSER": "chromium"
      }
    }
  }
}

使用 Docker 模式

npm run docker-build
npm run docker-run

Docker 模式会启动隔离的容器环境运行浏览器。

版本管理

版本信息

当前版本：0.0.75

资料来源：package.json:3

滚动更新

使用 roll.js 脚本更新 Playwright 版本：

npm run roll

该脚本会：

1. 更新 package.json 中的 Playwright 依赖版本
2. 从 Playwright 主仓库复制 config.d.ts
3. 重新生成 README 文档

更新后需要创建分支并提交 PR：

git checkout -b roll-pw-<version-suffix>
npm test
git commit -m "chore: roll Playwright to <version>"

资料来源：CLAUDE.md:14-23

贡献指南

提交流流程

graph TD
    A[创建 Issue] --> B{是否需要新功能?}
    B -->|是| C[描述问题并申请处理]
    B -->|否| D[找到已有 Issue]
    C --> E{是否分配给你?}
    D --> E
    E -->|否| F[等待分配]
    E -->|是| G[创建分支 fix-<issue-number>]
    G --> H[开发并添加测试]
    H --> I[提交 PR]
    I --> J[代码审查]
    J -->|通过| K[合并]
    J -->|拒绝| L[修改后重新提交]

提交规范

提交信息必须遵循 Semantic Commit Messages 格式：

<label>(<namespace>): <title>

<description>

<footer>

标签类型：

• fix: Bug 修复
• feat: 新功能
• docs: 文档更改
• test: 测试更改
• devops: CI/构建更改
• chore: 其他更改

PR 要求

• PR 必须关联一个 Issue 或经过批准
• PR 必须通过所有测试
• 代码必须通过 lint 检查：npm run lint
• PR 内容应保持小而可读

资料来源：CONTRIBUTING.md:1-40

常见问题

浏览器无法启动

确保已安装浏览器：

npx playwright install

测试超时

调整配置中的超时设置：

timeouts: {
  action: 10000,      // 增加操作超时
  navigation: 120000 // 增加导航超时
}

网络请求被阻止

检查 allowedOrigins 和 blockedOrigins 配置，确保目标域名在允许列表中。

概述

playwright-mcp 是 Microsoft Playwright 的 MCP（Model Context Protocol）实现，为大语言模型提供浏览器自动化能力。该项目作为 Playwright 与 MCP 协议之间的桥梁，使 AI Agent 能够通过标准化的 MCP 接口控制浏览器执行自动化任务。

核心架构采用模块化设计，核心功能依赖于 playwright-core 库，并通过 CLI 和 API 两种方式暴露能力。

系统架构图

graph TD
    subgraph 客户端层
        MCP_Client[MCP 客户端]
    end
    
    subgraph 核心模块
        Connection[createConnection]
        Tools[工具集合]
        CLI[CLI 入口]
    end
    
    subgraph Playwright 核心
        CoreBundle[coreBundle]
        Browser[浏览器自动化]
        Page[页面控制]
    end
    
    subgraph 配置系统
        Config[Config 类型定义]
        EnvVars[环境变量映射]
    end
    
    MCP_Client --> Connection
    Connection --> Tools
    Connection --> CoreBundle
    Tools --> Browser
    CoreBundle --> Browser
    CLI --> CoreBundle
    Config --> Connection

入口点设计

API 入口：index.js

主入口文件负责导出 MCP 连接工厂函数，供外部系统集成使用。

资料来源：index.js:25-27

const { tools } = require('playwright-core/lib/coreBundle');
module.exports = { createConnection: tools.createConnection };

设计特点：

• 极简导出设计，仅暴露 createConnection 函数
• 底层实现委托给 playwright-core 的 coreBundle
• 支持 Node.js 和 ES Module 环境

CLI 入口：cli.js

命令行入口点，支持多种操作模式。

资料来源：cli.js:1-34

const { program } = require('playwright-core/lib/utilsBundle');
const { tools, libCli } = require('playwright-core/lib/coreBundle');

if (process.argv.includes('install-browser')) {
  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);
  libCli.decorateProgram(program);
  void program.parseAsync(argv);
  return;
}

const packageJSON = require('./package.json');
const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
tools.decorateMCPCommand(p, packageJSON.version);

CLI 功能：

工具能力体系

能力分类

工具按照功能被组织为多个能力类别（ToolCapability）。

资料来源：config.d.ts:6-20

export type ToolCapability =
  'config' |
  'core' |
  'core-navigation' |
  'core-tabs' |
  'core-input' |
  'core-install' |
  'network' |
  'pdf' |
  'storage' |
  'testing' |
  'vision' |
  'devtools';

能力详情表

配置系统

配置类型定义

配置系统采用 TypeScript 类型定义，提供完整的类型安全配置。

资料来源：config.d.ts:23-150

核心配置结构：

export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    launchOptions?: Record<string, any>;
    initPage?: string[];
    initScript?: string[];
  },
  extension?: boolean;
  server?: {
    port?: number;
    host?: string;
    allowedHosts?: string[];
  },
  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  origins?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };
  testIdAttribute?: string;
  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };
  imageResponses?: 'allow' | 'omit' | 'auto';
  snapshot?: /* ... */;
}

配置项分类表

环境变量映射

CLI 选项自动映射为环境变量，提供灵活的部署配置。

资料来源：update-readme.js:66-85

模块依赖关系

graph LR
    subgraph 依赖层
        playwright-core
        playwright
        @playwright/test
    end
    
    subgraph 本项目
        index.js
        cli.js
        config.d.ts
    end
    
    playwright --> playwright-core
    @playwright/test --> playwright-core
    
    index.js --> playwright-core
    cli.js --> playwright-core

资料来源：package.json:17-40

{
  "name": "@playwright/mcp",
  "version": "0.0.75",
  "mcpName": "io.github.microsoft/playwright-mcp",
  "scripts": {
    "build": "echo OK",
    "test": "playwright test"
  },
  "dependencies": {
    "playwright-core": "..."
  },
  "devDependencies": {
    "@playwright/test": "...",
    "playwright": "..."
  }
}

构建与发布流程

版本管理机制

项目使用 roll.js 脚本同步 Playwright 依赖版本。

资料来源：roll.js:1-35

function copyConfig() {
  const src = path.join(__dirname, '..', 'playwright', 'packages', 'playwright-core', 'src', 'tools', 'mcp', 'config.d.ts');
  const dst = path.join(__dirname, 'config.d.ts');
  // 复制并替换导入路径
  content = content.replace(
    "import type * as playwright from 'playwright-core';",
    "import type * as playwright from 'playwright';"
  );
}

function updatePlaywrightVersion(version) {
  // 更新 package.json 中的依赖版本
}

function doRoll(version) {
  updatePlaywrightVersion(version);
  copyConfig();
  execSync('npm run lint', { cwd: __dirname });
}

版本更新流程

flowchart TD
    A[运行 npm run roll] --> B[updatePlaywrightVersion]
    B --> C[copyConfig 同步 config.d.ts]
    C --> D[npm install 安装依赖]
    D --> E[npm run lint 更新 README]
    E --> F[生成新版本提交]

npm Scripts 说明

MCP 工具注册机制

工具装饰器模式

工具通过 playwright-core 提供的装饰器注册到 MCP 命令系统。

资料来源：cli.js:28

tools.decorateMCPCommand(p, packageJSON.version);

README 自动生成

update-readme.js 脚本从编译后的模块自动提取工具信息并生成文档。

资料来源：update-readme.js:130-150

async function updateTools(content) {
  const generatedLines = [];
  for (const [capability, tools] of Object.entries(toolsByCapability)) {
    generatedLines.push(``);
  }
  // 使用标记替换机制更新 README
}

测试架构

测试配置

项目使用 @playwright/test 定义测试配置。

资料来源：playwright.config.ts:1-40

export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
    ...process.env.MCP_IN_DOCKER ? [{
      name: 'chromium-docker',
      grep: /browser_navigate|browser_click/,
      use: {
        mcpBrowser: 'chromium',
        mcpMode: 'docker' as const
      }
    }] : [],
  ],
});

测试项目矩阵

数据流向

sequenceDiagram
    participant MCP as MCP 客户端
    participant Server as MCP 服务器
    participant Tools as 工具层
    participant PW as Playwright Core
    participant Browser as 浏览器实例
    
    MCP->>Server: MCP 请求
    Server->>Tools: 调用工具
    Tools->>PW: Playwright API
    PW->>Browser: 浏览器控制
    Browser-->>PW: 执行结果
    PW-->>Tools: 返回结果
    Tools-->>Server: 格式化响应
    Server-->>MCP: MCP 响应

安全机制

来源控制

支持细粒度的请求来源控制。

资料来源：config.d.ts:88-100

origins?: {
  /**
   * 允许浏览器请求的来源列表
   * 支持格式：
   * - 完整来源: `https://example.com:8080`
   * - 通配符端口: `http://localhost:*`
   */
  allowedOrigins?: string[];

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

密钥管理

通过 secrets 配置支持敏感信息的安全传递。

与 Playwright 主仓库的关系

根据 CLAUDE.md 和 CONTRIBUTING.md 的说明：

[!WARNING]

The core of the Playwright MCP was moved to the Playwright monorepo.

当前仓库作为 Playwright 主仓库的 MCP 能力抽象层：

总结

playwright-mcp 的核心架构具有以下特点：

1. 极简入口设计：仅通过 createConnection 暴露核心功能
2. 委托实现模式：核心逻辑委托给 playwright-core
3. 类型安全配置：完整的 TypeScript 类型定义
4. 自动化文档：从源码自动生成 README
5. 版本同步机制：与 Playwright 主仓库保持同步
6. 灵活部署：支持环境变量、CLI 参数和编程式配置

概述

Playwright MCP (Model Context Protocol) 是微软官方提供的 Playwright 工具集，为大语言模型 (LLM) 提供浏览器自动化能力。该项目通过 MCP 协议暴露一系列可调用的工具，使 AI Agent 能够执行网页导航、元素交互、网络监控、PDF 操作等浏览器自动化任务。

根据 config.d.ts 中的定义，MCP 工具被组织为多个能力域 (Capability)，每个能力域包含一组相关的工具函数。资料来源：config.d.ts:20-33

架构概览

Playwright MCP 的源代码已迁移至 Playwright 主仓库，当前的 playwright-mcp 仓库作为依赖包装和分发层存在。资料来源：CONTRIBUTING.md:1-10

graph TD
    A[LLM / AI Agent] -->|MCP Protocol| B[Playwright MCP Server]
    B -->|工具调用| C[playwright-core]
    C --> D[Browser Automation]
    
    E[CLI / Config] -->|配置| B
    F[config.d.ts] -->|类型定义| E

能力域 (Tool Capabilities)

Playwright MCP 将工具划分为以下能力域，每个能力域对应不同的功能模块：

资料来源：config.d.ts:20-33

配置选项详解

基本配置结构

type Config = {
  browser?: BrowserConfig;
  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;
  console?: ConsoleConfig;
  network?: NetworkConfig;
  testIdAttribute?: string;
  timeouts?: TimeoutsConfig;
  imageResponses?: 'allow' | 'omit' | 'auto';
  snapshot?: SnapshotConfig;
};

资料来源：config.d.ts:36-120

浏览器配置

browser?: {
  browserName?: 'chromium' | 'firefox' | 'webkit';
  isolated?: boolean;
  userDataDir?: string;
  // ... launch options
}

超时配置

timeouts?: {
  action?: number;      // 默认动作超时，默认 5000ms
  navigation?: number;  // 默认导航超时，默认 60000ms
  expect?: number;      // 默认断言超时，默认 5000ms
}

资料来源：config.d.ts:60-74

网络安全配置

network?: {
  allowedOrigins?: string[];   // 允许的请求来源
  blockedOrigins?: string[];  // 阻止的请求来源
}

支持的格式：

资料来源：config.d.ts:84-95

控制台配置

console?: {
  level?: 'error' | 'warning' | 'info' | 'debug';
}

图片响应配置

imageResponses?: 'allow' | 'omit' | 'auto';

资料来源：config.d.ts:76-79

MCP 工具生成机制

README 文档中的工具列表通过 update-readme.js 脚本自动生成。脚本从编译后的模块加载工具信息，生成格式化的 Markdown 文档。资料来源：update-readme.js:1-100

graph LR
    A[编译后的模块] -->|加载工具| B[update-readme.js]
    B -->|生成 Markdown| C[README.md]
    
    D[cli.js --help] -->|CLI 选项| B
    E[config.d.ts] -->|配置类型| B

工具描述格式

每个工具在 README 中以折叠块形式展示：

# 浏览器配置文件管理

## 概述

浏览器配置文件管理是 Playwright MCP 的核心功能之一，允许用户通过配置对象自定义浏览器的启动行为、会话持久化方式以及浏览器上下文的安全策略。该模块通过 `config.d.ts` 中定义的 `Config` 类型提供类型安全的配置接口，支持多种浏览器引擎（Chromium、Firefox、WebKit）的灵活配置与管理。

Playwright MCP 的浏览器配置文件管理主要负责以下职责：

| 职责 | 说明 |
|------|------|
| 浏览器选择 | 指定使用哪种浏览器引擎 |
| 会话持久化 | 管理浏览器用户数据目录，支持会话恢复 |
| 安全策略 | 控制浏览器请求的来源限制（允许/阻止的域名） |
| 隔离模式 | 支持内存级浏览器配置文件，防止数据持久化 |
| 启动参数 | 传递自定义浏览器启动选项 |

资料来源：[config.d.ts:29-62]()

## 配置结构

### 顶级配置对象

Playwright MCP 的配置通过 `Config` 类型定义，核心结构如下：

export type Config = { browser?: { browserName?: 'chromium' | 'firefox' | 'webkit'; isolated?: boolean; userDataDir?: string; // 浏览器启动选项 }; // ... 其他配置项 };

资料来源：[config.d.ts:35-45]()

### 配置参数详解

#### 浏览器配置（browser）

浏览器配置对象包含以下可选参数：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `browserName` | `'chromium' \| 'firefox' \| 'webkit'` | `'chromium'` | 指定要使用的浏览器引擎 |
| `isolated` | `boolean` | `undefined` | 是否在内存中运行浏览器，不保存配置文件到磁盘 |
| `userDataDir` | `string` | `undefined` | 自定义浏览器用户数据目录路径 |

// 浏览器配置示例 const config = { browser: { browserName: 'chromium', isolated: true, userDataDir: '/path/to/custom/profile' } };

资料来源：[config.d.ts:35-62]()

#### 起源安全策略（network）

浏览器网络请求的安全策略通过 `network` 配置项管理：

| 参数 | 类型 | 说明 |
|------|------|------|
| `allowedOrigins` | `string[]` | 允许浏览器请求的来源列表，支持完整域名和通配符端口 |
| `blockedOrigins` | `string[]` | 阻止浏览器请求的来源列表，同时匹配两个列表的请求将被阻止 |

支持的来源格式：

- **完整域名**：`https://example.com:8080` - 仅匹配该具体地址
- **通配符端口**：`http://localhost:*` - 匹配 localhost 上任意端口的 HTTP 请求

const config = { network: { allowedOrigins: ['https://trusted-site.com'], blockedOrigins: ['https://untrusted-site.com'] } };

资料来源：[config.d.ts:103-126]()

#### 浏览器上下文配置（browserContext）

用于配置浏览器的上下文级设置：

| 参数 | 类型 | 说明 |
|------|------|------|
| `screenSize` | `{ width: number, height: number }` | 浏览器视口尺寸 |
| `timezoneId` | `string` | 浏览器的时区设置 |
| `locale` | `string` | 浏览器的区域设置 |
| `permissions` | `string[]` | 授予的浏览器权限列表 |
| `viewport` | `{ width: number, height: number }` | 默认视口大小 |

#### 测试标识属性（testIdAttribute）

指定用于测试 ID 的 HTML 属性，默认值为 `"data-testid"`：

const config = { testIdAttribute: 'data-testid' };

资料来源：[config.d.ts:71-77]()

#### 超时配置（timeouts）

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `action` | `number` | `5000` | 操作超时时间（毫秒） |
| `navigation` | `number` | `60000` | 导航超时时间（毫秒） |
| `expect` | `number` | `5000` | 断言超时时间（毫秒） |

const config = { timeouts: { action: 5000, navigation: 60000, expect: 5000 } };

资料来源：[config.d.ts:79-94]()

## 浏览器配置文件生命周期

### 配置文件创建流程

graph TD A[配置对象创建] --> B{userDataDir 设置?} B -->|是| C[使用指定目录] B -->|否| D{isolated 为 true?} D -->|是| E[创建临时内存目录] D -->|否| F[创建临时持久化目录] C --> G[浏览器启动] E --> G F --> G G --> H[浏览器上下文创建] H --> I[会话就绪]

### 会话持久化策略

Playwright MCP 支持三种会话持久化模式：

| 模式 | `isolated` | `userDataDir` | 行为 |
|------|------------|---------------|------|
| 完全隔离 | `true` | 未设置 | 浏览器配置存储在内存中，进程结束后丢失 |
| 临时持久化 | `false` | 未设置 | 临时目录存储配置，进程结束后自动清理 |
| 自定义持久化 | 任意 | 已设置 | 使用指定目录存储配置，可跨会话复用 |

// 完全隔离模式示例 const isolatedConfig = { browser: { browserName: 'chromium', isolated: true } };

// 跨会话复用配置示例 const persistentConfig = { browser: { browserName: 'chromium', userDataDir: '/path/to/persistent/profile' } };

资料来源：[config.d.ts:35-56]()

## 架构集成

### 组件关系图

graph TD subgraph "MCP 服务器层" A[index.js - createConnection] B[cli.js - 命令行解析] end

subgraph "配置管理层" C[config.d.ts - 类型定义] D[Config 验证器] end

subgraph "Playwright 核心" E[playwright-core] F[浏览器引擎] end

A --> B B --> D C --> D D --> E E --> F

style C fill:#e1f5fe style F fill:#fff3e0

### 配置文件加载流程

sequenceDiagram participant CLI as 命令行接口 participant Config as 配置加载器 participant Playwright as Playwright Core participant Browser as 浏览器引擎

CLI->>Config: 解析用户配置 Config->>Config: 验证配置类型 Config->>Playwright: 传递配置参数 Playwright->>Browser: 初始化浏览器 Browser-->>Playwright: 浏览器实例 Playwright-->>Config: 会话就绪 Config-->>CLI: MCP 服务启动

资料来源：[index.js:1-28]()

## 工具能力与浏览器配置

浏览器配置文件管理与 MCP 工具能力紧密集成，支持通过 `capabilities` 配置启用或禁用特定功能：

| 能力标识 | 说明 | 默认状态 |
|----------|------|----------|
| `core` | 核心浏览器操作 | 默认启用 |
| `core-navigation` | 页面导航功能 | 默认启用 |
| `core-tabs` | 多标签页管理 | 默认启用 |
| `core-input` | 输入操作 | 默认启用 |
| `core-install` | 浏览器安装 | 默认启用 |
| `network` | 网络请求拦截 | 需显式启用 |
| `pdf` | PDF 生成 | 需显式启用 |
| `storage` | 存储管理 | 需显式启用 |
| `testing` | 测试断言 | 需显式启用 |
| `vision` | 视觉交互 | 需显式启用 |
| `devtools` | 开发者工具 | 需显式启用 |

const config = { browser: { browserName: 'chromium' }, capabilities: ['core', 'network', 'pdf'] };

资料来源：[config.d.ts:28-32]()

## 使用示例

### 基础配置

import { createConnection } from '@playwright/mcp';

const server = createConnection({ browser: { browserName: 'chromium' } });

### 高级配置

import { createConnection } from '@playwright/mcp';

const server = createConnection({ browser: { browserName: 'firefox', isolated: false, userDataDir: '/home/user/.playwright-profiles/firefox', }, network: { allowedOrigins: ['https://example.com'], blockedOrigins: ['https://ads.example.com'] }, timeouts: { action: 10000, navigation: 120000 }, testIdAttribute: 'data-testid', outputDir: '/tmp/playwright-output' });

资料来源：[config.d.ts:35-140]()

### 命令行配置

Playwright MCP 通过 `cli.js` 提供命令行接口，支持通过命令行参数配置浏览器行为：

使用指定浏览器

npx playwright-mcp --browser=chromium

安装浏览器

npx playwright-mcp install-browser

查看帮助

npx playwright-mcp --help

资料来源：[cli.js:1-31]()

## 相关源码文件索引

| 文件路径 | 作用 |
|----------|------|
| `config.d.ts` | 配置类型定义，包含所有浏览器配置接口 |
| `index.js` | MCP 连接入口，导出 `createConnection` |
| `cli.js` | 命令行工具，处理用户输入和参数解析 |
| `playwright.config.ts` | 测试框架配置，用于项目内部测试 |
| `package.json` | 包元数据，定义 MCP 服务名称和版本 |

## 配置验证

Playwright MCP 在启动时会验证配置对象的有效性。配置验证主要包括：

1. **类型检查**：确保所有配置项符合 TypeScript 类型定义
2. **值域验证**：检查枚举值（如浏览器类型）是否有效
3. **路径验证**：验证 `userDataDir` 等路径是否存在或可创建

配置验证失败时，MCP 服务器将抛出类型错误并拒绝启动，确保用户能够及时发现配置问题。

资料来源：[config.d.ts:1-140]()

概述

初始状态配置（Initial State Configuration）是指 Playwright MCP Server 启动时的各项运行时参数与选项。这些配置项决定了浏览器的启动方式、会话管理策略、网络安全策略、超时行为等核心功能。配置文件采用 TypeScript 类型定义，统一存放在 config.d.ts 中，并通过 CLI 参数、环境变量或编程方式传递给服务端。

配置架构

graph TD
    A[Playwright MCP Server] --> B[配置加载层]
    B --> C[CLI 参数]
    B --> D[环境变量]
    B --> E[配置文件]
    
    C --> F[配置合并与验证]
    D --> F
    E --> F
    
    F --> G[Config 对象]
    
    G --> H[browser 配置]
    G --> I[capabilities 配置]
    G --> J[network 配置]
    G --> K[timeouts 配置]
    G --> L[其他选项]
    
    H --> M[Playwright Browser]
    I --> N[可用工具集]
    J --> O[网络请求过滤]
    K --> P[超时策略]

核心配置项

浏览器配置

浏览器配置通过 browser 字段定义，控制浏览器实例的创建与生命周期管理。

isolated 模式说明：isolated 为 true 时，浏览器配置不会保存到磁盘，所有会话数据存储在内存中，浏览器关闭后自动清除。设置为 false 并配合 userDataDir 可实现浏览器状态的持久化保存。

能力配置

capabilities 数组定义了 MCP Server 暴露给客户端的工具能力集。

export type ToolCapability =
  'config' |
  'core' |
  'core-navigation' |
  'core-tabs' |
  'core-input' |
  'core-install' |
  'network' |
  'pdf' |
  'storage' |
  'testing' |
  'vision' |
  'devtools';

网络安全配置

network 字段用于控制浏览器可访问的网络来源，实现请求来源的白名单与黑名单管理。

network?: {
  allowedOrigins?: string[];
  blockedOrigins?: string[];
};

支持的格式

匹配优先级：当某个 origin 同时匹配 allowedOrigins 和 blockedOrigins 时，该请求将被阻止。

超时配置

timeouts 对象定义了各类操作的默认超时时间。

timeouts?: {
  action?: number;      // 默认: 5000ms
  navigation?: number; // 默认: 60000ms
  expect?: number;      // 默认: 5000ms
};

会话与上下文管理

会话保存

浏览器上下文共享

安全配置

密钥管理

secrets?: Record<string, string>;

secrets 用于替换工具响应中的匹配明文文本，防止 LLM 意外获取敏感数据。

注意：这是便利性功能而非安全特性，客户端仍需始终检查传入和来自工具的信息。

图片响应控制

imageResponses?: 'allow' | 'omit' | 'auto';

其他配置项

测试 ID 属性

testIdAttribute?: string;

指定用于测试 ID 的属性，默认为 data-testid。

输出目录

outputDir?: string;

保存输出文件的目录路径。

控制台日志级别

console?: {
  level?: 'error' | 'warning' | 'info' | 'debug';
};

每种级别包含更严重级别的消息：debug < info < warning < error。

配置传递方式

Playwright MCP 支持多种配置传递方式：

1. CLI 参数

通过命令行启动时传递参数：

npx playwright-mcp --browser-name=chromium --output-dir=/tmp/pw-output

2. 环境变量

每个 CLI 参数都有对应的环境变量：

环境变量通过 update-readme.js 脚本自动从 CLI 定义生成。资料来源：update-readme.js:62-67

3. 编程配置

通过 Config 类型定义配置对象：

import type { Config } from '@playwright/mcp';

const config: Config = {
  browser: {
    browserName: 'chromium',
    isolated: true
  },
  capabilities: ['core', 'network'],
  timeouts: {
    action: 10000,
    navigation: 30000
  }
};

配置类型定义

完整的 Config 类型定义如下：

export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    // ... 其他启动选项
  };
  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;
  console?: {
    level?: 'error' | 'warning' | 'info' | 'debug';
  };
  network?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };
  testIdAttribute?: string;
  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };
  imageResponses?: 'allow' | 'omit' | 'auto';
  snapshot?: /* Snapshot 配置 */;
};

资料来源：config.d.ts:1-100

测试配置

对于测试场景，Playwright MCP 使用独立的 playwright.config.ts 配置文件：

export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
  ],
});

资料来源：playwright.config.ts:1-30

配置验证流程

graph LR
    A[输入配置] --> B[类型检查]
    B --> C{合法?}
    C -->|是| D[应用配置]
    C -->|否| E[抛出错误]
    
    D --> F[浏览器启动]
    D --> G[工具注册]
    D --> H[网络策略应用]
    D --> I[超时设置]

最佳实践

1. 隔离环境：使用 isolated: true 避免浏览器状态污染
2. 超时设置：根据网络环境调整 timeouts 数值
3. 网络安全：生产环境应明确设置 allowedOrigins 白名单
4. 密钥保护：通过 secrets 配置敏感信息，避免硬编码
5. 能力精简：仅启用必需的 capabilities，减少攻击面

概述

Playwright MCP 是一个为 MCP（Model Context Protocol）协议提供 Playwright 工具的项目。它允许 AI 助手通过标准化的接口控制浏览器执行各种自动化任务，包括导航、点击、输入、网络请求拦截等操作。资料来源：package.json:1-10

为了确保在自动化浏览器操作过程中的安全性，项目提供了多层次的安全配置机制：

• 网络请求控制：通过 allowedOrigins 和 blockedOrigins 白名单/黑名单机制
• 敏感信息保护：通过 secrets 配置实现敏感数据的自动替换
• 浏览器隔离：通过 browser.isolated 等选项控制浏览器实例的生命周期

资料来源：config.d.ts:1-150

网络配置

源地址过滤

Playwright MCP 提供了精细的网络请求控制功能，允许管理员指定允许或阻止的请求源地址。

#### allowedOrigins（允许的源地址）

支持的匹配格式：

当请求同时匹配 allowedOrigins 和 blockedOrigins 时，该请求将被阻止。

资料来源：config.d.ts:50-75

#### blockedOrigins（阻止的源地址）

graph TD
    A[浏览器发起请求] --> B{检查 blockedOrigins}
    B -->|匹配黑名单| C[阻止请求]
    B -->|未匹配黑名单| D{检查 allowedOrigins}
    D -->|已配置且匹配| E[允许请求]
    D -->|已配置但未匹配| C
    D -->|未配置| E

配置示例：

{
  network: {
    // 允许所有本地开发服务器
    allowedOrigins: [
      'http://localhost:3000',
      'http://localhost:8080',
      'http://127.0.0.1:*'
    ],
    // 阻止所有外部 API 请求
    blockedOrigins: [
      'https://api.external-service.com'
    ]
  }
}

资料来源：config.d.ts:60-90

网络配置结构

完整的网络配置类型定义如下：

network?: {
  allowedOrigins?: string[];
  blockedOrigins?: string[];
};

浏览器配置与安全隔离

浏览器实例选项

Playwright MCP 支持配置浏览器实例的各项参数，以满足不同的安全需求。

#### 隔离模式（isolated）

启用隔离模式后，浏览器不会将任何持久化数据（如 Cookie、缓存、本地存储）写入磁盘。这对于安全性要求较高的自动化场景特别有用。

{
  browser: {
    browserName: 'chromium',
    isolated: true  // 启用内存隔离模式
  }
}

资料来源：config.d.ts:30-55

用户数据目录管理

通过 userDataDir 可以自定义浏览器配置文件的存储位置。默认情况下，系统会创建临时目录存储浏览器数据。

资料来源：config.d.ts:35-45

敏感信息安全

Secrets 配置

Playwright MCP 提供了 secrets 配置选项，用于在工具响应中自动替换敏感信息，防止大语言模型意外获取敏感数据。

重要提示：secrets 功能是便利性功能而非安全特性。它主要用于防止 LLM 意外泄露敏感数据，但不应将其视为真正的安全加密手段。请确保始终对客户端传入的信息进行仔细检查。

资料来源：config.d.ts:110-120

#### Secrets 配置结构

secrets?: Record<string, string>;

#### 使用方式

{
  secrets: {
    // key: 要替换的敏感值
    // value: 替换后的显示值
    'my-api-key-12345': '[REDACTED]',
    'Bearer token_xyz': '[REDACTED]'
  }
}

#### 替换机制

当工具响应中包含匹配 secrets 中定义的键值时，对应的敏感信息会被替换为预设的显示值：

graph LR
    A[工具响应生成] --> B{检查 secrets 配置}
    B -->|发现敏感信息| C[替换为预设值]
    B -->|无敏感信息| D[保持原样]
    C --> E[返回处理后的响应]
    D --> E

资料来源：update-readme.js:80-95

Console 日志级别控制

通过 console.level 配置可以控制返回给客户端的日志消息级别：

{
  console: {
    level: 'info'  // 默认值
  }
}

资料来源：config.d.ts:125-135

配置选项参考

完整配置类型定义

export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    launchOptions?: Record<string, any>;
  };

  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;

  console?: {
    level?: 'error' | 'warning' | 'info' | 'debug';
  };

  network?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };

  testIdAttribute?: string;

  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };

  imageResponses?: 'allow' | 'omit' | 'auto';
  snapshot?: Record<string, any>;
};

资料来源：config.d.ts:95-145

CLI 环境变量映射

CLI 选项与环境变量的映射关系：

资料来源：update-readme.js:60-80

安全最佳实践

开发环境配置

// 开发环境配置示例
{
  browser: {
    browserName: 'chromium',
    isolated: false  // 开发环境可复用浏览器状态
  },
  network: {
    allowedOrigins: ['http://localhost:*'],
    blockedOrigins: ['https://production-api.example.com']
  },
  console: {
    level: 'debug'
  }
}

生产环境配置

// 生产环境配置示例
{
  browser: {
    browserName: 'chromium',
    isolated: true  // 生产环境启用隔离
  },
  network: {
    allowedOrigins: [
      'https://app.example.com',
      'https://cdn.example.com'
    ],
    blockedOrigins: ['*']
  },
  secrets: {
    'api-key-xxx': '[REDACTED]',
    'session-token': '[REDACTED]'
  },
  console: {
    level: 'error'  // 仅返回错误信息
  }
}

安全检查清单

在部署 Playwright MCP 之前，建议检查以下安全配置：

安全漏洞报告

微软对软件产品的安全性非常重视，包括所有通过 GitHub 组织管理的源代码仓库。

报告流程

请勿通过公开的 GitHub Issues 报告安全漏洞。

应按照以下方式向 Microsoft Security Response Center (MSRC) 报告：

1. 访问：https://msrc.microsoft.com/create-report
2. 或发送邮件至：[email protected]
3. 如可能，请使用 PGP 密钥加密消息（可从 Microsoft Security Response Center PGP Key 页面下载）

通常情况下，您将在 24 小时内收到回复。

资料来源：SECURITY.md:1-30

报告内容建议

在报告时，请尽可能提供以下信息以帮助我们更好地理解和处理问题：

• 问题类型
• 完整的产品路径
• 受影响的组件
• 复现步骤
• 建议的修复方案（可选）

相关文档

贡献指南

如果发现安全相关问题或希望为项目贡献代码，请注意以下事项：

1. 问题优先：在提交 PR 之前，请先提交或查找相关的问题（issue）
2. 提交规范：提交信息应遵循语义化提交规范（Semantic Commit Messages）
3. 分支命名：问题修复的分支命名格式为 fix-<issue-number>

资料来源：CONTRIBUTING.md:1-50

# 创建修复分支示例
git checkout -b fix-39562

# 提交修复
git commit -m "fix(proxy): handle SOCKS proxy authentication"

资料来源：CLAUDE.md:1-40

概述

Playwright MCP 是一个基于 Model Context Protocol (MCP) 的浏览器自动化工具，它将 Playwright 的强大功能封装为一组 MCP 工具，供 AI 代理和自动化系统使用。部署选项的设计目标是为开发者提供灵活的选择，无论是本地开发、测试环境还是生产环境，都能找到合适的部署方式。

根据 package.json 中的配置，Playwright MCP 需要 Node.js 18 或更高版本运行环境，并通过 npm 进行包管理 资料来源：package.json:8

Node.js 环境部署

环境要求

安装步骤

在 Node.js 环境中部署 Playwright MCP 的标准流程如下：

# 克隆仓库
git clone https://github.com/microsoft/playwright-mcp
cd playwright-mcp

# 安装依赖
npm ci

# 安装浏览器（Chromium、Firefox、WebKit）
npx playwright install

运行 MCP 服务器

Playwright MCP 提供了两种运行模式：通过 CLI 直接运行或作为模块导入使用。

#### CLI 模式

直接使用 CLI 运行 MCP 服务器：

# 查看可用选项
npm run lint

# 运行测试
npm test

# 仅运行 Chromium 测试
npm run ctest

#### 模块导入模式

在 JavaScript 或 TypeScript 项目中作为模块使用：

const { createConnection } = require('@playwright/mcp');
// 或 ESM
import { createConnection } from '@playwright/mcp';

资料来源：index.js:25

MCP 测试配置

在 playwright.config.ts 中，测试配置支持多种运行方式：

export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
  ],
});

资料来源：playwright.config.ts:20-30

Docker 容器部署

Docker 部署提供了一致的运行环境，特别适合 CI/CD 场景和需要隔离环境的开发团队。

Dockerfile 构建

Playwright MCP 提供了预配置的 Dockerfile 用于构建容器镜像：

# 构建镜像
npm run docker-build

# 运行容器
npm run docker-run

手动构建命令：

docker build --no-cache -t playwright-mcp-dev:latest .

容器运行参数

Docker 测试模式

在 Docker 环境中运行测试需要设置特定的环境变量：

# 在 Docker 中运行 Chromium 测试
npm run dtest

内部实现使用 MCP_IN_DOCKER=1 环境变量触发特殊配置：

MCP_IN_DOCKER=1 playwright test --project=chromium-docker

playwright.config.ts 中 Docker 测试配置：

...process.env.MCP_IN_DOCKER ? [{
  name: 'chromium-docker',
  grep: /browser_navigate|browser_click/,
  use: {
    mcpBrowser: 'chromium',
    mcpMode: 'docker' as const
  }
}] : [],

资料来源：playwright.config.ts:21-27

容器生命周期管理

# 构建镜像
npm run docker-build

# 运行容器
npm run docker-run

# 停止并删除容器
npm run docker-rm

资料来源：package.json:15-17

CLI 命令行工具

CLI 入口点

CLI 通过 cli.js 实现，基于 commander.js 构建：

const { program } = require('playwright-core/lib/utilsBundle');
const { tools, libCli } = require('playwright-core/lib/coreBundle');

资料来源：cli.js:15-16

install-browser 命令

CLI 支持通过 install-browser 别名安装浏览器：

npx playwright-mcp install-browser
# 或
node cli.js install-browser

内部实现将 install-browser 转换为 install 命令：

if (process.argv.includes('install-browser')) {
  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);
  libCli.decorateProgram(program);
  void program.parseAsync(argv);
  return;
}

资料来源：cli.js:12-18

MCP 命令装饰

CLI 使用 Playwright Core 的 MCP 工具装饰功能：

const packageJSON = require('./package.json');
const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
tools.decorateMCPCommand(p, packageJSON.version);

资料来源：cli.js:21-24

配置选项

配置类型定义

Playwright MCP 的配置通过 TypeScript 类型定义在 config.d.ts 中，支持多种配置选项。

资料来源：config.d.ts:1-100

浏览器配置

超时配置

timeouts?: {
  action?: number;      // 默认操作超时，默认 5000ms
  navigation?: number; // 默认导航超时，默认 60000ms
  expect?: number;     // 默认 expect 超时，默认 5000ms
};

来源控制配置

Playwright MCP 支持细粒度的来源控制：

支持的格式：

• 完整来源：https://example.com:8080 - 仅匹配该来源
• 通配符端口：http://localhost:* - 匹配 localhost 上任意端口的 HTTP 请求

图像响应配置

imageResponses?: 'allow' | 'omit' | 'auto';
// 默认值为 "auto"，如果客户端可以显示则发送图像

测试 ID 属性

testIdAttribute?: string;
// 指定用于测试 ID 的属性，默认为 "data-testid"

快照配置

snapshot?: {
  // 快照相关配置选项
};

功能模块与部署关系

可用功能模块

Playwright MCP 将工具按功能模块组织，不同的模块可能需要不同的部署配置：

Opt-in 模块可通过 --caps 参数启用：

--caps=network,pdf,storage

资料来源：config.d.ts:13-28

部署架构图

graph TD
    A[开发者环境] --> B[Node.js 部署]
    A --> C[Docker 容器部署]
    A --> D[CLI 工具部署]
    
    B --> B1[直接运行]
    B --> B2[模块导入]
    
    C --> C1[容器构建]
    C --> C2[容器运行]
    C --> C3[测试模式]
    
    D --> D1[install-browser]
    D --> D2[MCP 命令]
    
    B1 --> E[playwright-core]
    B2 --> E
    C2 --> E
    E --> F[浏览器实例]
    
    F --> G[Chromium]
    F --> H[Firefox]
    F --> I[WebKit]

环境变量

最佳实践

开发环境

• 使用 npm ci 安装依赖确保构建一致性
• 本地运行 npx playwright install 安装所需浏览器
• 使用 npm run ctest 快速验证 Chromium 功能

CI/CD 环境

• 优先使用 Docker 容器确保环境一致性
• 设置 CI=true 以启用严格的测试模式
• 使用 npm test 运行完整测试套件

生产环境

• 考虑使用 browser.isolated 选项提高安全性
• 根据需求配置 allowedOrigins 和 blockedOrigins
• 设置合适的 timeouts 值避免长时间等待

故障排查

常见问题

诊断命令

# 检查 Node.js 版本
node --version

# 检查 Playwright 安装
npx playwright --version

# 查看 CLI 帮助
node cli.js --help

Pitfall Log / 踩坑日志

项目：microsoft/playwright-mcp

摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 playwright-mcp 与安装入口 @playwright/mcp@latest 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npx @playwright/mcp@latest
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | repo=playwright-mcp; install=@playwright/mcp@latest

2. 安装坑 · 来源证据：Bad entrypoint in docker example

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bad entrypoint in docker example
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_948f818745694481b19e883b3992d78b | https://github.com/microsoft/playwright-mcp/issues/1609 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：v0.0.72

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.0.72
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2e67eb76e3c643e0a52a97e42eca4cb8 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72 | 来源类型 github_release 暴露的待验证使用条件。

4. 配置坑 · 来源证据：v0.0.69

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.69
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6767d649d4934031b85ab0c5ffc2b324 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：v0.0.71

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.71
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d5bcb1704c0e4a6fb375b18cda153fdd | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71 | 来源类型 github_release 暴露的待验证使用条件。

6. 配置坑 · 来源证据：v0.0.73

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.73
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a0d6aead61ad4c52ab738c6b556f2e27 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73 | 来源类型 github_release 暴露的待验证使用条件。

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | README/documentation is current enough for a first validation pass.

8. 运行坑 · 来源证据：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening af…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening after Release v0.0.69.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e8f29958fbbe48ce8381daa23333bdf4 | https://github.com/microsoft/playwright-mcp/issues/1607 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 运行坑 · 来源证据：v0.0.67

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.67
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3b13c720c21346bab9c08783c91acb95 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.67 | 来源类型 github_release 暴露的待验证使用条件。

10. 运行坑 · 来源证据：v0.0.68

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.68
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c53eae5fa6a94d2e86bc60cf6b164d16 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.68 | 来源类型 github_release 暴露的待验证使用条件。

11. 运行坑 · 来源证据：v0.0.74

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.74
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2c41b3bf29434fb48d51cb9ffc766fc2 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.74 | 来源类型 github_release 暴露的待验证使用条件。

12. 运行坑 · 来源证据：v0.0.75

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.75
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4e21e73e13dc471f90365f431d541143 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.75 | 来源类型 github_release 暴露的待验证使用条件。

13. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | last_activity_observed missing

14. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium

15. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium

16. 安全/权限坑 · 来源证据：VS Code installation buttons don't seem to work

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：VS Code installation buttons don't seem to work
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_37c3461084f34d05856db207d12f8d9a | https://github.com/microsoft/playwright-mcp/issues/1608 | 来源类型 github_issue 暴露的待验证使用条件。

17. 安全/权限坑 · 来源证据：[Bug]: Windows taskkill output can pollute MCP stdio transport

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Windows taskkill output can pollute MCP stdio transport
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_789c261c74274d9d9a84d4b1fbf30d14 | https://github.com/microsoft/playwright-mcp/issues/1611 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fc2b3d242d67495f81f1bb1877e22f84 | https://github.com/microsoft/playwright-mcp/issues/1617 | 来源类型 github_issue 暴露的待验证使用条件。

19. 安全/权限坑 · 来源证据：[Feature Request] Support clientCertificates option for mTLS authentication

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Support clientCertificates option for mTLS authentication
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b6f82bec73944aa5869030ad7db55b0c | https://github.com/microsoft/playwright-mcp/issues/1456 | 来源类型 github_issue 暴露的待验证使用条件。

20. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | issue_or_pr_quality=unknown

21. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | release_recency=unknown