microsoft--playwright-mcp/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Playwright MCP

一个基于 Playwright. 的 Model Context Protocol（MCP）服务器，提供浏览器自动化能力。该服务器使 LLM 能够通过结构化的可访问性快照与网页交互，无需截图或依赖视觉调优模型。

Playwright MCP 与 Playwright CLI

本包为 Playwright 提供 MCP 接口。若你使用的是编程代理（coding agent），使用 CLI+SKILLS 可能更合适。

• CLI：现代编程代理越来越倾向于将基于 CLI 的工作流以 SKILL 形式暴露，而不是 MCP，因为 CLI 调用更节省 token：它们避免将大型工具 schema 和冗长的可访问性树加载到模型上下文中，使代理能够通过简洁、专用的命令执行操作。这使得 CLI + SKILLs 更适合高吞吐的编程代理——这类代理必须在有限的上下文窗口内，在浏览器自动化与大型代码库、测试和推理之间取得平衡。
  了解更多：Playwright CLI with SKILLS.**

• MCP：MCP 仍适用于受益于持久状态、丰富内省能力以及对页面结构进行迭代推理的专用智能体循环，例如探索性自动化、自愈测试，或长时间运行的自主工作流——在这些场景中，维持连续的浏览器上下文比 token 成本更重要。

主要特性

• 快速且轻量。使用 Playwright 的可访问性树，而非基于像素的输入。
• 对 LLM 友好。无需视觉模型，完全基于结构化数据运行。
• 确定性的工具调用。避免基于截图方案常见的歧义。

要求

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

快速开始

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

标准配置适用于大多数工具：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

Amp

通过 Amp VS Code 扩展设置界面添加，或更新你的 settings.json 文件：

"amp.mcpServers": {
  "playwright": {
    "command": "npx",
    "args": [
      "@playwright/mcp@latest"
    ]
  }
}

Amp CLI 设置：

通过下方 amp mcp add 命令添加

amp mcp add playwright -- npx @playwright/mcp@latest

Antigravity

通过 Antigravity 设置添加，或更新你的配置文件：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

Claude Code

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

claude mcp add playwright npx @playwright/mcp@latest

Claude Desktop

按照 MCP 安装指南, 使用上方标准配置。

Cline

按照 Configuring MCP Servers 章节中的说明操作。

示例：本地设置

将以下内容添加到你的 cline_mcp_settings.json 文件中：

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ],
      "disabled": false
    }
  }
}

Codex

使用 Codex CLI 添加 Playwright MCP 服务器：

codex mcp add playwright npx "@playwright/mcp@latest"

或者，创建或编辑配置文件 ~/.codex/config.toml 并添加：

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

更多信息请参阅 Codex MCP documentation.

Copilot

使用 Copilot CLI 以交互方式添加 Playwright MCP 服务器：

/mcp add

或者，创建或编辑配置文件 ~/.copilot/mcp-config.json 并添加：

{
  "mcpServers": {
    "playwright": {
      "type": "local",
      "command": "npx",
      "tools": [
        "*"
      ],
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

更多信息请参阅 Copilot CLI documentation.

Cursor

点击按钮安装：

或手动安装：

前往 Cursor Settings -> MCP -> Add new MCP Server。名称可自定，类型选择 command，命令为 npx @playwright/mcp@latest。也可通过点击 Edit 验证配置或添加命令参数。

Factory

使用 Factory CLI 添加 Playwright MCP 服务器：

droid mcp add playwright "npx @playwright/mcp@latest"

或者，在 Factory droid 中输入 /mcp，打开用于管理 MCP 服务器的交互式界面。

更多信息请参阅 Factory MCP documentation.

Gemini CLI

按照 MCP 安装指南, 使用上方标准配置。

Goose

点击按钮安装：

或手动安装：

前往 Advanced settings -> Extensions -> Add custom extension。名称可自定，类型使用 STDIO，并将 command 设为 npx @playwright/mcp。点击 "Add Extension"。

Grok

使用 Grok CLI 添加 Playwright MCP 服务器：

grok mcp add playwright -- npx @playwright/mcp@latest

或者，创建或编辑配置文件 ~/.grok/config.toml 并添加：

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

更多信息请参阅 Grok MCP documentation.

Junie

在 Junie CLI 中添加 Playwright MCP 服务器：

1. 输入 /mcp
2. 按 Ctrl+A 添加新的 MCP 服务器
3. 从列表中选择 Playwright

或者，添加到 .junie/mcp/mcp.json：

{
  "mcpServers": {
    "Playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  }
}

更多信息请参阅 Junie MCP 配置文档.

Kiro

请遵循 MCP Servers 文档. 例如在 .kiro/settings/mcp.json 中：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

LM Studio

点击按钮安装：

或手动安装：

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

opencode

请遵循 MCP Servers 文档. 例如在 ~/.config/opencode/opencode.json 中：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@playwright/mcp@latest"
      ],
      "enabled": true
    }
  }
}

Qodo Gen

在 VSCode 或 IntelliJ 中打开 Qodo Gen 聊天面板 → 连接更多工具 → + 添加新 MCP → 粘贴上方的标准配置。

点击 Save。

VS Code

点击按钮安装：

或手动安装：

请遵循 MCP 安装 指南, 使用上方的标准配置。你也可以使用 VS Code CLI 安装 Playwright MCP 服务器：

# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

安装完成后，即可在 VS Code 中将 Playwright MCP 服务器用于你的 GitHub Copilot agent。

Warp

转到 Settings -> AI -> Manage MCP Servers -> + Add 以添加 MCP 服务器. 使用上方的标准配置。

或者，在 Warp 提示符中使用斜杠命令 /add-mcp，并粘贴上方的标准配置：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

Windsurf

请遵循 Windsurf MCP 文档. 使用上方的标准配置。

配置

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

Option	Description
--allowed-hosts <hosts...>	逗号分隔的主机列表，指定此服务器允许提供服务的主机。默认为服务器绑定的主机。传入 '*' 可禁用主机检查。 env PLAYWRIGHT_MCP_ALLOWED_HOSTS
--allowed-origins	分号分隔的受信任来源（TRUSTED origins）列表，允许浏览器发起请求。默认允许所有来源。重要：不构成安全边界，不影响重定向。 env PLAYWRIGHT_MCP_ALLOWED_ORIGINS
--allow-unrestricted-file-access	允许访问工作区根目录之外的文件。同时允许无限制访问 file:// URL。默认情况下，文件系统访问仅限于工作区根目录（若未配置根目录则为 cwd），且禁止导航到 file:// URL。 env PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS
--blocked-origins	分号分隔的来源列表，阻止浏览器发起请求。阻止列表在允许列表之前评估。若在未使用允许列表的情况下使用，不匹配阻止列表的请求仍会被允许。重要：不构成安全边界，不影响重定向。 env PLAYWRIGHT_MCP_BLOCKED_ORIGINS
--block-service-workers	阻止 Service Worker env PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS
--browser	要使用的浏览器或 Chrome 渠道，可选值：chrome、firefox、webkit、msedge。 env PLAYWRIGHT_MCP_BROWSER
--caps	逗号分隔的额外功能列表，可选值：vision、pdf、devtools。 env PLAYWRIGHT_MCP_CAPS
--cdp-endpoint	要连接的 CDP 端点。 env PLAYWRIGHT_MCP_CDP_ENDPOINT
--cdp-header <headers...>	随连接请求发送的 CDP 请求头，可指定多个。 env PLAYWRIGHT_MCP_CDP_HEADERS
--cdp-timeout	连接 CDP 端点的超时时间（毫秒），默认为 30000ms env PLAYWRIGHT_MCP_CDP_TIMEOUT
--codegen	指定代码生成使用的语言，可选值："typescript"、"none"。默认为 "typescript"。 env PLAYWRIGHT_MCP_CODEGEN
--config	配置文件路径。 env PLAYWRIGHT_MCP_CONFIG
--console-level	要返回的控制台消息级别："error"、"warning"、"info"、"debug"。每个级别都包含更严重级别的消息。 env PLAYWRIGHT_MCP_CONSOLE_LEVEL
--device	要模拟的设备，例如："iPhone 15" env PLAYWRIGHT_MCP_DEVICE
--mobile	模拟通用移动设备（Chromium 为 Pixel 10，WebKit 为 iPhone 17）。移动页面通常更轻量，可节省 token。不能与 --device 组合使用。 env PLAYWRIGHT_MCP_MOBILE
--executable-path	浏览器可执行文件路径。 env PLAYWRIGHT_MCP_EXECUTABLE_PATH
--extension	连接到正在运行的浏览器实例（仅 Edge/Chrome）。需要安装 "Playwright Extension"。 env PLAYWRIGHT_MCP_EXTENSION
--endpoint	要连接的绑定浏览器端点。 env PLAYWRIGHT_MCP_ENDPOINT
--grant-permissions <permissions...>	授予浏览器上下文的权限列表，例如 "geolocation"、"clipboard-read"、"clipboard-write"。 env PLAYWRIGHT_MCP_GRANT_PERMISSIONS
--headless	以无头模式运行浏览器，默认为有界面模式 env PLAYWRIGHT_MCP_HEADLESS
--host	服务器绑定的主机。默认为 localhost。使用 0.0.0.0 可绑定到所有网络接口。 env PLAYWRIGHT_MCP_HOST
--ignore-https-errors	忽略 HTTPS 错误 env PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS
--init-page <path...>	在 Playwright page 对象上求值的 TypeScript 文件路径 env PLAYWRIGHT_MCP_INIT_PAGE
--init-script <path...>	作为初始化脚本添加的 JavaScript 文件路径。该脚本会在页面任何脚本之前在每个页面上求值。可多次指定。 env PLAYWRIGHT_MCP_INIT_SCRIPT
--isolated	将浏览器配置文件保存在内存中，不写入磁盘。 env PLAYWRIGHT_MCP_ISOLATED
--image-responses	是否向客户端发送图像响应。可为 "allow" 或 "omit"，默认为 "allow"。 env PLAYWRIGHT_MCP_IMAGE_RESPONSES
--no-sandbox	为所有通常启用沙箱的进程类型禁用沙箱。 env PLAYWRIGHT_MCP_NO_SANDBOX
--output-dir	输出文件目录路径。 env PLAYWRIGHT_MCP_OUTPUT_DIR
--output-max-size	驱逐旧输出文件的阈值（字节）。 env PLAYWRIGHT_MCP_OUTPUT_MAX_SIZE
--output-mode	是否将快照、控制台消息、网络日志保存到文件或标准输出。可为 "file" 或 "stdout"。默认为 "stdout"。 env PLAYWRIGHT_MCP_OUTPUT_MODE
--port	SSE 传输监听的端口。 env PLAYWRIGHT_MCP_PORT
--proxy-bypass	绕过代理的域名列表（逗号分隔），例如 ".com,chromium.org,.domain.com" env PLAYWRIGHT_MCP_PROXY_BYPASS
--proxy-server	指定代理服务器，例如 "http://myproxy:3128" 或 "socks5://myproxy:8080" env PLAYWRIGHT_MCP_PROXY_SERVER
--sandbox	为所有通常未启用沙箱的进程类型启用沙箱。 env PLAYWRIGHT_MCP_SANDBOX
--save-session	是否将 Playwright MCP 会话保存到输出目录。 env PLAYWRIGHT_MCP_SAVE_SESSION
--secrets	包含 dotenv 格式密钥的文件路径 env PLAYWRIGHT_MCP_SECRETS_FILE
--shared-browser-context	在所有已连接的 HTTP 客户端之间复用同一浏览器上下文。 env PLAYWRIGHT_MCP_SHARED_BROWSER_CONTEXT
--snapshot-mode	为响应拍摄快照时指定使用的模式。可为 "full" 或 "none"。默认为 "full"。 env PLAYWRIGHT_MCP_SNAPSHOT_MODE
--storage-state	隔离会话的 storage state 文件路径 env PLAYWRIGHT_MCP_STORAGE_STATE
--test-id-attribute	指定用于测试 ID 的属性，默认为 "data-testid" env PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE
--timeout-action	指定操作超时时间（毫秒），默认为 5000ms env PLAYWRIGHT_MCP_TIMEOUT_ACTION
--timeout-navigation	指定导航超时时间（毫秒），默认为 60000ms env PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION
--user-agent	指定 User-Agent 字符串 env PLAYWRIGHT_MCP_USER_AGENT
--user-data-dir	用户数据目录路径。若未指定，将创建临时目录。 env PLAYWRIGHT_MCP_USER_DATA_DIR
--viewport-size	指定浏览器视口大小（像素），例如 "1280x720" env PLAYWRIGHT_MCP_VIEWPORT_SIZE

用户配置文件

你可以像在常规浏览器中一样，使用持久化配置文件（默认）运行 Playwright MCP，在隔离上下文中进行测试会话，或通过浏览器扩展连接到你现有的浏览器。

持久化配置文件

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

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

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

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

{workspace-hash} 派生自 MCP 客户端的工作区根目录，因此不同项目会自动获得独立的配置文件。

Important

持久化配置文件同一时间只能被一个浏览器实例使用，因此共享同一工作区的并发 MCP 客户端会发生冲突。要并行运行多个客户端，请为每个额外客户端使用 --isolated 启动，或将其指向不同的 --user-data-dir。

隔离模式

在隔离模式下，每个会话都在隔离配置文件中启动。每当你要求 MCP 关闭浏览器时， 会话就会关闭，该会话的所有存储状态（storage state）也会丢失。你可以通过配置中的 contextOptions 或 --storage-state 参数向浏览器提供初始存储状态。了解更多关于存储状态的内容，请参见此处.

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

浏览器扩展

Playwright MCP Chrome 扩展允许你连接到现有的浏览器标签页，并利用你已登录的会话和浏览器状态。安装与设置说明请参见 microsoft/playwright › packages/extension

初始状态

有多种方式可向浏览器上下文（browser context）或页面提供初始状态。

对于存储状态，你可以：

• 使用 --user-data-dir 参数，从用户数据目录（user data directory）启动。这会在会话之间持久保存所有浏览器数据。
• 使用 --storage-state 参数，从存储状态文件启动。这会将文件中的 cookies 和 local storage 加载到隔离的浏览器上下文中。

对于页面状态，你可以使用：

• --init-page 可指向一个 TypeScript 文件，该文件会在 Playwright 页面对象上执行。这允许你运行任意代码来设置页面。

// init-page.ts
export default async ({ page }) => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
  await page.setViewportSize({ width: 1280, height: 720 });
};

• --init-script 可指向一个 JavaScript 文件，该文件会作为初始化脚本添加。此脚本会在页面任何脚本之前于每个页面上执行。 这适用于覆盖浏览器 API 或设置环境。

// init-script.js
window.isPlaywrightMCP = true;

配置文件

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

npx @playwright/mcp@latest --config path/to/config.json

配置文件模式（schema）

{
  /**
   * The browser to use.
   */
  browser?: {
    /**
     * The type of browser to use.
     */
    browserName?: 'chromium' | 'firefox' | 'webkit';

    /**
     * Keep the browser profile in memory, do not save it to disk.
     */
    isolated?: boolean;

    /**
     * Path to a user data directory for browser profile persistence.
     * Temporary directory is created by default.
     */
    userDataDir?: string;

    /**
     * Launch options passed to
     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
     *
     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
     */
    launchOptions?: playwright.LaunchOptions;

    /**
     * Context options for the browser context.
     *
     * This is useful for settings options like `viewport`.
     */
    contextOptions?: playwright.BrowserContextOptions;

    /**
     * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
     */
    cdpEndpoint?: string;

    /**
     * CDP headers to send with the connect request.
     */
    cdpHeaders?: Record<string, string>;

    /**
     * Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
     */
    cdpTimeout?: number;

    /**
     * Remote endpoint to connect to an existing Playwright server. May be a
     * WebSocket URL string, or a [ConnectOptions] object that mirrors the
     * `connectOptions` shape used by the test runner. When passed as an object,
     * `exposeNetwork`, `headers`, `slowMo`, and `timeout` are forwarded to the
     * underlying connect call.
     */
    remoteEndpoint?: string | playwright.ConnectOptions & { endpoint: string };

    /**
     * Paths to TypeScript files to add as initialization scripts for Playwright page.
     */
    initPage?: string[];

    /**
     * Paths to JavaScript files to add as initialization scripts.
     * The scripts will be evaluated in every page before any of the page's scripts.
     */
    initScript?: string[];
  },

  /**
   * Connect to a running browser instance (Edge/Chrome only). If specified, `browser`
   * config is ignored.
   * Requires the "Playwright Extension" to be installed.
   */
  extension?: boolean;

  server?: {
    /**
     * The port to listen on for SSE or MCP transport.
     */
    port?: number;

    /**
     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
     */
    host?: string;

    /**
     * The hosts this server is allowed to serve from. Defaults to the host server is bound to.
     * This is not for CORS, but rather for the DNS rebinding protection.
     */
    allowedHosts?: string[];
  },

  /**
   * List of enabled tool capabilities. Possible values:
   *   - 'core': Core browser automation features.
   *   - 'pdf': PDF generation and manipulation.
   *   - 'vision': Coordinate-based interactions.
   *   - 'devtools': Developer tools features.
   */
  capabilities?: ToolCapability[];

  /**
   * Whether to save the Playwright session into the output directory.
   */
  saveSession?: boolean;

  /**
   * Reuse the same browser context between all connected HTTP clients.
   */
  sharedBrowserContext?: boolean;

  /**
   * Secrets are used to replace matching plain text in the tool responses to prevent the LLM
   * from accidentally getting sensitive data. It is a convenience and not a security feature,
   * make sure to always examine information coming in and from the tool on the client.
   */
  secrets?: Record<string, string>;

  /**
   * The directory to save output files.
   */
  outputDir?: string;

  /**
   * Threshold for evicting old output files, in bytes.
   */
  outputMaxSize?: number;

  console?: {
    /**
     * The level of console messages to return. Each level includes the messages of more severe levels. Defaults to "info".
     */
    level?: 'error' | 'warning' | 'info' | 'debug';
  },

  network?: {
    /**
     * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
     *
     * Supported formats:
     * - Full origin: `https://example.com:8080` - matches only that origin
     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
     */
    allowedOrigins?: string[];

    /**
     * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
     *
     * Supported formats:
     * - Full origin: `https://example.com:8080` - matches only that origin
     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
     */
    blockedOrigins?: string[];
  };

  /**
   * Specify the attribute to use for test ids, defaults to "data-testid".
   */
  testIdAttribute?: string;

  timeouts?: {
    /*
     * Configures default action timeout: https://playwright.dev/docs/api/class-page#page-set-default-timeout. Defaults to 5000ms.
     */
    action?: number;

    /*
     * Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.
     */
    navigation?: number;

    /**
     * Configures default expect timeout: https://playwright.dev/docs/test-timeouts#expect-timeout. Defaults to 5000ms.
     */
    expect?: number;
  };

  /**
   * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
   */
  imageResponses?: 'allow' | 'omit';

  snapshot?: {
    /**
     * When taking snapshots for responses, specifies the mode to use.
     */
    mode?: 'full' | 'none';
  };

  /**
   * allowUnrestrictedFileAccess acts as a guardrail to prevent the LLM from accidentally
   * wandering outside its intended workspace. It is a convenience defense to catch unintended
   * file access, not a secure boundary; a deliberate attempt to reach other directories can be
   * easily worked around, so always rely on client-level permissions for true security.
   */
  allowUnrestrictedFileAccess?: boolean;

  /**
   * Specify the language to use for code generation.
   */
  codegen?: 'typescript' | 'none';
}

独立 MCP 服务器

在无显示器的系统上运行有界面（headed）浏览器，或从 IDE 的工作进程运行时， 请在配置了 DISPLAY 的环境中运行 MCP 服务器，并传入 --port 标志以启用 HTTP 传输。

npx @playwright/mcp@latest --port 8931

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

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

安全

Playwright MCP 并非安全边界。请参阅 MCP Security Best Practices) 了解如何保护你的部署。

Docker

注意： 目前的 Docker 实现仅支持 headless chromium。

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

或者，如果你希望将容器作为长期运行的服务，而不是由 MCP 客户端启动，请使用：

docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  --name playwright \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  /app/cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0

服务器将在主机端口 8931 上监听，任何 MCP 客户端均可访问。

你可以自行构建 Docker 镜像。

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

编程式使用

import http from 'http';

import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

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

  // Creates a headless Playwright MCP server with SSE transport
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);

  // ...
});

工具

核心自动化

• browser_click
  • 标题：点击
  • 描述：在网页上执行点击操作
  • 参数：
    • element (string, optional)：用于获取与元素交互权限的人类可读元素描述
    • target (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
    • doubleClick (boolean, optional)：是否执行双击而非单击
    • button (string, optional)：要点击的按钮，默认为 left
    • modifiers (array, optional)：要按下的修饰键
  • 只读：false

• browser_close
  • 标题：关闭浏览器
  • 描述：关闭页面
  • 参数：无
  • 只读：false

• browser_console_messages
  • 标题：获取控制台消息
  • 描述：返回所有控制台消息
  • 参数：
    • level (string)：要返回的控制台消息级别。每个级别包含更严重级别的消息。默认为 "info"。
    • all (boolean, optional)：返回自会话开始以来的所有控制台消息，而不仅仅是自上次导航以来的消息。默认为 false。
    • filename (string, optional)：用于保存控制台消息的文件名。如未提供，则以文本形式返回消息。
  • 只读：true

• browser_drag
  • 标题：拖动鼠标
  • 描述：在两个元素之间执行拖放操作
  • 参数：
    • startElement (string, optional)：用于获取与源元素交互权限的人类可读源元素描述
    • startTarget (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
    • endElement (string, optional)：用于获取与目标元素交互权限的人类可读目标元素描述
    • endTarget (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
  • 只读：false

• browser_drop
  • 标题：将文件或数据拖放到元素上
  • 描述：将文件或 MIME 类型的数据拖放到元素上，如同从页面外部拖入。必须至少提供 "paths" 或 "data" 之一。
  • 参数：
    • element (string, optional)：用于获取与元素交互权限的人类可读元素描述
    • target (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
    • paths (array, optional)：要拖放到元素上的文件的绝对路径。
    • data (object, optional)：要拖放的数据，以 MIME 类型到字符串值的映射形式提供（例如 {"text/plain": "hello", "text/uri-list": "https://example.com"}）。
  • 只读：false

• browser_evaluate
  • 标题：执行 JavaScript
  • 描述：在页面或元素上执行 JavaScript 表达式
  • 参数：
    • element (string, optional)：用于获取与元素交互权限的人类可读元素描述
    • target (string, optional)：来自页面快照的精确目标元素引用，或唯一的元素选择器
    • function (string)：() => { /* code / } 或当提供 element 时为 (element) => { / code */ }
    • filename (string, optional)：用于保存结果的文件名。如未提供，则以文本形式返回结果。
  • 只读：false

• browser_file_upload
  • 标题：上传文件
  • 描述：上传一个或多个文件
  • 参数：
    • paths (array, optional)：要上传文件的绝对路径。可以是单个文件或多个文件。如省略，则取消文件选择器。
  • 只读：false

• browser_fill_form
  • 标题：填写表单
  • 描述：填写多个表单字段
  • 参数：
    • fields (array)：要填写的字段
  • 只读：false

• browser_find
  • 标题：在页面快照中查找
  • 描述：在当前页面的无障碍（accessibility）快照中搜索文本或正则表达式。返回匹配的快照节点及少量周围上下文（类似搜索片段），每个节点均显示其在树中的路径；当你只需定位元素及其 ref 时，这比捕获整个快照更节省开销。
  • 参数：
    • text (string, optional)：要在页面快照中搜索的纯文本（不区分大小写的子串匹配）。请提供 text 或 regex 之一，不要同时提供。
    • regex (string, optional)：要在页面快照中搜索的正则表达式。默认区分大小写；用斜杠包裹模式以添加标志，例如 "/error/i" 表示不区分大小写。请提供 text 或 regex 之一，不要同时提供。
  • 只读：true

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

• browser_hover
  • 标题：悬停鼠标
  • 描述：在页面元素上悬停
  • 参数：
    • element (string, optional)：用于获取与元素交互权限的人类可读元素描述
    • target (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
  • 只读：false

• browser_navigate
  • Title: 导航到 URL
  • Description: 导航到 URL
  • Parameters:
    • url (string): 要导航到的 URL
  • Read-only: false

• browser_navigate_back
  • Title: 后退
  • Description: 返回历史记录中的上一页
  • Parameters: None
  • Read-only: false

• browser_network_request
  • Title: 显示网络请求详情
  • Description: 返回单个网络请求的完整详情（headers 和 body），若设置了 part 则仅返回其中一部分。请使用 browser_network_requests 输出的编号。
  • Parameters:
    • index (integer): 请求的 1-based 索引，与 browser_network_requests 输出的编号一致。
    • part (string, optional): 仅返回请求的此部分。省略则返回完整详情。
    • filename (string, optional): 将结果保存到的文件名。若未提供，则以文本形式返回输出。
  • Read-only: true

• browser_network_requests
  • Title: 列出网络请求
  • Description: 返回自页面加载以来的网络请求编号列表。使用 browser_network_request 并传入编号可获取完整详情。
  • Parameters:
    • static (boolean): 是否包含成功的静态资源（如图片、字体、脚本等）。默认为 false。
    • filter (string, optional): 仅返回 URL 匹配此正则表达式的请求（例如 "/api/.*user"）。
    • filename (string, optional): 将网络请求保存到的文件名。若未提供，则以文本形式返回请求。
  • Read-only: true

• browser_press_key
  • Title: 按键
  • Description: 在键盘上按下一个键
  • Parameters:
    • key (string): 要按下的键名或要生成的字符，例如 ArrowLeft 或 a
  • Read-only: false

• browser_resize
  • Title: 调整浏览器窗口大小
  • Description: 调整浏览器窗口大小
  • Parameters:
    • width (number): 浏览器窗口宽度
    • height (number): 浏览器窗口高度
  • Read-only: false

• browser_run_code_unsafe
  • Title: 运行 Playwright 代码（不安全）
  • Description: 运行一段 Playwright 代码片段。不安全：在 Playwright 服务器进程中执行任意 JavaScript，等效于远程代码执行（RCE）。
  • Parameters:
    • code (string, optional): 包含待执行 Playwright 代码的 JavaScript 函数。将以单个参数 page 调用，可用于任意页面交互。例如：async (page) => { await page.getByRole('button', { name: 'Submit' }).click(); return await page.title(); }
    • filename (string, optional): 从指定文件加载代码。若同时提供 code 和 filename，将忽略 code。
  • Read-only: false

• browser_select_option
  • Title: 选择选项
  • Description: 在下拉框中选择选项
  • Parameters:
    • element (string, optional): 用于获取与元素交互权限的人类可读元素描述
    • target (string): 来自页面快照的精确目标元素引用，或唯一元素选择器
    • values (array): 要在下拉框中选择的值数组。可以是单个值或多个值。
  • Read-only: false

• browser_snapshot
  • Title: 页面快照
  • Description: 捕获当前页面的无障碍（accessibility）快照，优于截图
  • Parameters:
    • target (string, optional): 来自页面快照的精确目标元素引用，或唯一元素选择器
    • filename (string, optional): 将快照保存为 Markdown 文件，而非在响应中返回。
    • depth (number, optional): 限制快照树的深度
    • boxes (boolean, optional): 在快照中包含每个元素的边界框，格式为 [box=x,y,width,height]。坐标相对于视口，单位为 CSS 像素（Element.getBoundingClientRect）
  • Read-only: true

• browser_take_screenshot
  • Title: 截图
  • Description: 对当前页面截图。无法基于截图执行操作，请使用 browser_snapshot 进行操作。
  • Parameters:
    • element (string, optional): 用于获取与元素交互权限的人类可读元素描述
    • target (string, optional): 来自页面快照的精确目标元素引用，或唯一元素选择器
    • type (string): 截图的图像格式。默认为 png。
    • filename (string, optional): 保存截图的文件名。若未指定，默认为 page-{timestamp}.{png|jpeg}。建议使用相对文件名以保持在输出目录内。
    • fullPage (boolean, optional): 为 true 时，截取完整可滚动页面的截图，而非当前可见视口。不能与元素截图同时使用。
    • scale (string): 图像分辨率缩放。"css" 生成以 CSS 像素计尺寸的截图（较小，跨设备一致）。"device" 使用设备像素生成高分辨率截图（较大，考虑设备像素比）。默认为 css。
  • Read-only: true

• browser_type
  • Title: 输入文本
  • Description: 在可编辑元素中输入文本
  • Parameters:
    • element (string, optional): 用于获取与元素交互权限的人类可读元素描述
    • target (string): 来自页面快照的精确目标元素引用，或唯一元素选择器
    • text (string): 要输入到元素中的文本
    • submit (boolean, optional): 是否提交已输入的文本（之后按 Enter）
    • slowly (boolean, optional): 是否逐字符输入。适用于触发页面中的按键处理程序。默认情况下会一次性填入全部文本。
  • Read-only: false

• browser_wait_for
  • Title: 等待
  • Description: 等待文本出现或消失，或等待指定时间过去
  • Parameters:
    • time (number, optional): 等待时间（秒）
    • text (string, optional): 要等待出现的文本
    • textGone (string, optional): 要等待消失的文本
  • Read-only: false

标签页管理

• browser_tabs
  • Title: 管理标签页
  • Description: 列出、创建、关闭或选择浏览器标签页。
  • Parameters:
    • action (string): 要执行的操作
    • index (number, optional): 标签页索引，用于 close/select。close 时若省略，则关闭当前标签页。
    • url (string, optional): 在新标签页中导航到的 URL，用于 new。
  • Read-only: false

浏览器安装

配置（通过 --caps=config 可选启用）

• browser_get_config
  • Title: 获取配置
  • Description: 获取合并 CLI 选项、环境变量和配置文件后的最终解析配置。
  • Parameters: None
  • Read-only: true

网络（通过 --caps=network 可选启用）

• browser_network_state_set
  • Title: 设置网络状态
  • Description: 将浏览器网络状态设置为 online 或 offline。offline 时，所有网络请求都会失败。
  • Parameters:
    • state (string): 设为 "offline" 以模拟离线模式，设为 "online" 以恢复网络连接
  • Read-only: false

• browser_route
  • Title: 模拟网络请求
  • Description: 设置路由以模拟匹配 URL 模式的网络请求
  • Parameters:
    • pattern (string): 要匹配的 URL 模式（例如 "/api/users"、"/*.{png,jpg}"）
    • status (number, optional): 要返回的 HTTP 状态码（默认：200）
    • body (string, optional): 响应体（文本或 JSON 字符串）
    • contentType (string, optional): Content-Type 标头（例如 "application/json"、"text/html"）
    • headers (array, optional): 以 "Name: Value" 格式添加的标头
    • removeHeaders (string, optional): 要从请求中移除的标头名称列表，以逗号分隔
  • Read-only: false

• browser_route_list
  • Title: 列出网络路由
  • Description: 列出所有活动的网络路由
  • Parameters: None
  • Read-only: true

• browser_unroute
  • Title: 移除网络路由
  • Description: 移除匹配指定模式的网络路由（若未指定模式则移除所有路由）
  • Parameters:
    • pattern (string, optional): 要取消路由的 URL 模式（省略则移除所有路由）
  • Read-only: false

Storage（通过 --caps=storage 可选启用）

• browser_cookie_clear
  • Title: 清除 Cookie
  • Description: 清除所有 Cookie
  • Parameters: None
  • Read-only: false

• browser_cookie_delete
  • Title: 删除 Cookie
  • Description: 删除指定的 Cookie
  • Parameters:
    • name (string): 要删除的 Cookie 名称
  • Read-only: false

• browser_cookie_get
  • Title: 获取 Cookie
  • Description: 按名称获取指定的 Cookie
  • Parameters:
    • name (string): 要获取的 Cookie 名称
  • Read-only: true

• browser_cookie_list
  • Title: 列出 Cookie
  • Description: 列出所有 Cookie（可按域名/路径可选过滤）
  • Parameters:
    • domain (string, optional): 按域名过滤 Cookie
    • path (string, optional): 按路径过滤 Cookie
  • Read-only: true

• browser_cookie_set
  • Title: 设置 Cookie
  • Description: 设置 Cookie，并可选配置标志（domain、path、expires、httpOnly、secure、sameSite）
  • Parameters:
    • name (string): Cookie 名称
    • value (string): Cookie 值
    • domain (string, optional): Cookie 域名
    • path (string, optional): Cookie 路径
    • expires (number, optional): Cookie 过期时间（Unix 时间戳）
    • httpOnly (boolean, optional): Cookie 是否为 HTTP only
    • secure (boolean, optional): Cookie 是否为 secure
    • sameSite (string, optional): Cookie SameSite 属性
  • Read-only: false

• browser_localstorage_clear
  • Title: 清除 localStorage
  • Description: 清除所有 localStorage
  • Parameters: None
  • Read-only: false

• browser_localstorage_delete
  • Title: 删除 localStorage 项
  • Description: 删除 localStorage 项
  • Parameters:
    • key (string): 要删除的键
  • Read-only: false

• browser_localstorage_get
  • Title: 获取 localStorage 项
  • Description: 按键获取 localStorage 项
  • Parameters:
    • key (string): 要获取的键
  • Read-only: true

• browser_localstorage_list
  • Title: 列出 localStorage
  • Description: 列出所有 localStorage 键值对
  • Parameters: None
  • Read-only: true

• browser_localstorage_set
  • Title: 设置 localStorage 项
  • Description: 设置 localStorage 项
  • Parameters:
    • key (string): 要设置的键
    • value (string): 要设置的值
  • Read-only: false

• browser_sessionstorage_clear
  • Title: 清除 sessionStorage
  • Description: 清除所有 sessionStorage
  • Parameters: None
  • Read-only: false

• browser_sessionstorage_delete
  • Title: 删除 sessionStorage 项
  • Description: 删除 sessionStorage 项
  • Parameters:
    • key (string): 要删除的键
  • Read-only: false

• browser_sessionstorage_get
  • Title: 获取 sessionStorage 项
  • Description: 按键获取 sessionStorage 项
  • Parameters:
    • key (string): 要获取的键
  • Read-only: true

• browser_sessionstorage_list
  • Title: 列出 sessionStorage
  • Description: 列出所有 sessionStorage 键值对
  • Parameters: None
  • Read-only: true

• browser_sessionstorage_set
  • Title: 设置 sessionStorage 项
  • Description: 设置 sessionStorage 项
  • Parameters:
    • key (string): 要设置的键
    • value (string): 要设置的值
  • Read-only: false

• browser_set_storage_state
  • Title: 恢复存储状态
  • Description: 从文件恢复存储状态（Cookie、local storage）。恢复前会清除现有的 Cookie 和 local storage。
  • Parameters:
    • filename (string): 要从中恢复的存储状态文件路径
  • Read-only: false

• browser_storage_state
  • Title: 保存存储状态
  • Description: 将存储状态（Cookie、local storage）保存到文件，供后续复用
  • Parameters:
    • filename (string, optional): 保存存储状态的文件名。若未指定，则默认为 storage-state-{timestamp}.json。
  • Read-only: true

DevTools（通过 --caps=devtools 可选启用）

• browser_annotate
  • Title: 标注当前页面
  • Description: 以标注模式为当前页面打开 Playwright Dashboard，并等待用户绘制标注。返回带标注的截图、ARIA 快照以及标注列表。
  • Parameters: None
  • Read-only: true

• browser_hide_highlight
  • Title: 隐藏元素高亮
  • Description: 移除先前为该元素添加的高亮叠加层。
  • Parameters:
    • element (string, optional): 添加高亮时使用的人类可读元素描述；必须与传递给 browser_highlight 的值一致。
    • target (string, optional): 页面快照中的精确目标元素引用，或唯一的元素选择器
  • Read-only: true

• browser_highlight
  • Title: 高亮元素
  • Description: 在页面上显示围绕该元素的持久高亮叠加层。
  • Parameters:
    • element (string, optional): 用于获取与元素交互权限的人类可读元素描述
    • target (string): 页面快照中的精确目标元素引用，或唯一的元素选择器
    • style (string, optional): 应用于高亮叠加层的额外内联 CSS，例如 "outline: 2px dashed red"。
  • Read-only: true

• browser_resume
  • Title: 恢复已暂停的脚本执行
  • Description: 在脚本暂停后恢复执行。当 step 设为 true 时，执行会在下一个操作前再次暂停。
  • Parameters:
    • step (boolean, optional): 为 true 时，执行会在下一个操作前再次暂停，以便逐步调试。
    • location (string, optional): 在指定的 : 处暂停执行，例如 "example.spec.ts:42"。
  • Read-only: false

• browser_start_tracing
  • Title: 开始追踪
  • Description: 开始记录追踪
  • Parameters: 无
  • Read-only: true

• browser_start_video
  • Title: 开始录制视频
  • Description: 开始录制视频
  • Parameters:
    • filename (string, optional): 用于保存视频的文件名。
    • size (object, optional): 视频尺寸
  • Read-only: true

• browser_stop_tracing
  • Title: 停止追踪
  • Description: 停止记录追踪
  • Parameters: 无
  • Read-only: true

• browser_stop_video
  • Title: 停止录制视频
  • Description: 停止录制视频
  • Parameters: 无
  • Read-only: true

• browser_video_chapter
  • Title: 视频章节
  • Description: 为视频录制添加章节标记。会显示带模糊背景的满屏章节卡片。
  • Parameters:
    • title (string): 章节标题
    • description (string, optional): 章节描述
    • duration (number, optional): 章节卡片显示时长（毫秒）
  • Read-only: true

• browser_video_hide_actions
  • Title: 隐藏操作叠加层
  • Description: 停止标注页面上执行的操作。
  • Parameters: 无
  • Read-only: true

• browser_video_show_actions
  • Title: 显示操作叠加层
  • Description: 为页面上后续执行的操作添加标注：通过标注框显示操作名称并高亮目标元素。适用于视频录制或屏幕录制（screencasting）时。
  • Parameters:
    • duration (number, optional): 每个操作标注在屏幕上停留的时长（毫秒）。默认为 500。
    • position (string, optional): 操作标题相对于页面的显示位置。默认为 top-right。
    • cursor (string, optional): 指针操作的鼠标光标装饰。"pointer"（默认）会将鼠标指针从上一个操作点动画移动到下一个操作点；"none" 会禁用光标装饰。
  • Read-only: true

基于坐标（通过 --caps=vision 可选启用）

• browser_mouse_click_xy
  • Title: 点击
  • Description: 在指定位置点击鼠标按钮
  • Parameters:
    • x (number): X 坐标
    • y (number): Y 坐标
    • button (string, optional): 要点击的按钮，默认为 left
    • clickCount (number, optional): 点击次数，默认为 1
    • delay (number, optional): 鼠标按下与松开之间的等待时间（毫秒），默认为 0
  • Read-only: false

• browser_mouse_down
  • Title: 按下鼠标
  • Description: 按下鼠标
  • Parameters:
    • button (string, optional): 要按下的按钮，默认为 left
  • Read-only: false

• browser_mouse_drag_xy
  • Title: 拖动鼠标
  • Description: 将鼠标左键拖动到指定位置
  • Parameters:
    • startX (number): 起始 X 坐标
    • startY (number): 起始 Y 坐标
    • endX (number): 结束 X 坐标
    • endY (number): 结束 Y 坐标
  • Read-only: false

• browser_mouse_move_xy
  • Title: 移动鼠标
  • Description: 将鼠标移动到指定位置
  • Parameters:
    • x (number): X 坐标
    • y (number): Y 坐标
  • Read-only: false

• browser_mouse_up
  • Title: 松开鼠标
  • Description: 松开鼠标
  • Parameters:
    • button (string, optional): 要松开的按钮，默认为 left
  • Read-only: false

• browser_mouse_wheel
  • Title: 滚动鼠标滚轮
  • Description: 滚动鼠标滚轮
  • Parameters:
    • deltaX (number): X 增量
    • deltaY (number): Y 增量
  • Read-only: false

PDF 生成（通过 --caps=pdf 可选启用）

• browser_pdf_save
  • Title: 另存为 PDF
  • Description: 将页面另存为 PDF
  • Parameters:
    • filename (string, optional): 用于保存 PDF 的文件名。若未指定，则默认为 page-{timestamp}.pdf。建议使用相对文件名，以保留在输出目录内。
  • Read-only: true

测试断言（通过 --caps=testing 可选启用）

• browser_generate_locator
  • Title: 为元素创建定位器（locator）
  • Description: 为给定元素生成定位器，供测试使用
  • Parameters:
    • element (string, optional): 用于获取与元素交互权限的人类可读元素描述
    • target (string): 来自页面快照的精确目标元素引用，或唯一元素选择器
  • Read-only: true

• browser_verify_element_visible
  • Title: 验证元素可见
  • Description: 验证元素在页面上可见
  • Parameters:
    • role (string): 元素的 ROLE。可在快照中这样找到：- {ROLE} "Accessible Name":
    • accessibleName (string): 元素的 ACCESSIBLE_NAME。可在快照中这样找到：- role "{ACCESSIBLE_NAME}"
  • Read-only: false

• browser_verify_list_visible
  • Title: 验证列表可见
  • Description: 验证列表在页面上可见
  • Parameters:
    • element (string): 人类可读的列表描述
    • target (string): 指向该列表的精确目标元素引用
    • items (array): 要验证的条目
  • Read-only: false

• browser_verify_text_visible
  • Title: 验证文本可见
  • Description: 验证文本在页面上可见。如有可能，请优先使用 browser_verify_element_visible。
  • Parameters:
    • text (string): 要验证的 TEXT。可在快照中这样找到：- role "Accessible Name": {TEXT}，或这样：- text: {TEXT}
  • Read-only: false

• browser_verify_value
  • Title: 验证值
  • Description: 验证元素值
  • Parameters:
    • type (string): 元素类型
    • element (string): 人类可读的元素描述
    • target (string): 来自页面快照的精确目标元素引用
    • value (string): 要验证的值。对于复选框（checkbox），请使用 "true" 或 "false"。
  • Read-only: false