AI导哈

浏览器自动化服务

Playwright MCP是一个基于Playwright的浏览器自动化服务器，提供结构化可访问性快照，使LLM能够通过纯结构化数据与网页交互，无需视觉模型或截图。

  • by ornaw
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 ornaw/playwright-mcp-repo

使用说明

剧作家MCP

一个提供浏览器自动化功能的模型上下文协议（MCP）服务器，通过 剧作家这个服务器使大型语言模型（LLMs）能够通过结构化的无障碍快照与网页进行交互，从而省去了截取屏幕截图或使用视觉调优模型的步骤。

主要特点

  • 快速且轻便使用Playwright的无障碍性树，而非基于像素的输入。
  • 对大型语言模型（LLM）友好无需视觉模型，仅基于结构化数据运行。
  • 确定性工具应用避免了基于截图方法常见的歧义问题。

要求

  • Node.js 18 或更高版本
  • VS Code、Cursor、Windsurf、Claude Desktop、Goose 或任何其他 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
Claude Code

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

claude mcp add playwright npx @playwright/mcp@latest
Claude Desktop

按照MCP安装程序进行安装 指南/引导，使用上述标准配置。

Codex

创建或编辑配置文件 ~/.codex/config.toml 并补充：

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

如需更多信息，请参阅 MCP代码库文档。

Cursor

点击按钮进行安装：

或者手动安装：

首选 Cursor Settings -> MCP -> Add new MCP Server按您的喜好命名，使用 command 使用命令输入类型 npx @playwright/mcp@latest您也可以通过点击来验证配置或添加类似命令的参数 Edit。

Gemini CLI

按照MCP安装指南进行安装 指南；引导使用上面的标准配置。

Goose

点击按钮进行安装：

或者手动安装：

首选 Advanced settings -> Extensions -> Add custom extension按您的喜好命名，使用（您喜欢的）字体 STDIO，并设置 command 到 npx @playwright/mcp点击“添加扩展”。

Kiro

关注MCP服务器 文件资料例如，在 .kiro/settings/mcp.json：

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

点击按钮进行安装：

或者手动安装：

首选 Program 在右侧边栏中 -> Install -> Edit mcp.json使用上述标准配置。

opencode

关注MCP服务器 文档；说明书；资料例如，在 ~/.config/opencode/opencode.json：

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

开放 Qodo Gen（假设这是一个特定名称或品牌，直接音译） 在VSCode或IntelliJ中的聊天面板 → 连接更多工具 → + 添加新的MCP → 粘贴上述标准配置。

点击 保存。

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 代理进行配合。

Warp

首选 Settings -> AI -> Manage MCP Servers -> + Add 到 添加一个MCP服务器使用上述标准配置。

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

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

跟随风帆冲浪MCP（多用途控制协议或特定应用协议，具体含义依上下文而定） 文档使用上述标准配置。

配置

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

> npx @playwright/mcp@latest --help
  --allowed-hosts <hosts...>            comma-separated list of hosts this
                                        server is allowed to serve from.
                                        Defaults to the host the server is bound
                                        to. Pass '*' to disable the host check.
  --allowed-origins <origins>           semicolon-separated list of origins to
                                        allow the browser to request. Default is
                                        to allow all.
  --blocked-origins <origins>           semicolon-separated list of origins to
                                        block the browser from requesting.
                                        Blocklist is evaluated before allowlist.
                                        If used without the allowlist, requests
                                        not matching the blocklist are still
                                        allowed.
  --block-service-workers               block service workers
  --browser <browser>                   browser or chrome channel to use,
                                        possible values: chrome, firefox,
                                        webkit, msedge.
  --caps <caps>                         comma-separated list of additional
                                        capabilities to enable, possible values:
                                        vision, pdf.
  --cdp-endpoint <endpoint>             CDP endpoint to connect to.
  --cdp-header <headers...>             CDP headers to send with the connect
                                        request, multiple can be specified.
  --config <path>                       path to the configuration file.
  --device <device>                     device to emulate, for example: "iPhone
                                        15"
  --executable-path <path>              path to the browser executable.
  --extension                           Connect to a running browser instance
                                        (Edge/Chrome only). Requires the
                                        "Playwright MCP Bridge" browser
                                        extension to be installed.
  --grant-permissions <permissions...>  List of permissions to grant to the
                                        browser context, for example
                                        "geolocation", "clipboard-read",
                                        "clipboard-write".
  --headless                            run browser in headless mode, headed by
                                        default
  --host <host>                         host to bind server to. Default is
                                        localhost. Use 0.0.0.0 to bind to all
                                        interfaces.
  --ignore-https-errors                 ignore https errors
  --init-script <path...>               path to JavaScript file to add as an
                                        initialization script. The script will
                                        be evaluated in every page before any of
                                        the page's scripts. Can be specified
                                        multiple times.
  --isolated                            keep the browser profile in memory, do
                                        not save it to disk.
  --image-responses <mode>              whether to send image responses to the
                                        client. Can be "allow" or "omit",
                                        Defaults to "allow".
  --no-sandbox                          disable the sandbox for all process
                                        types that are normally sandboxed.
  --output-dir <path>                   path to the directory for output files.
  --port <port>                         port to listen on for SSE transport.
  --proxy-bypass <bypass>               comma-separated domains to bypass proxy,
                                        for example
                                        ".com,chromium.org,.domain.com"
  --proxy-server <proxy>                specify proxy server, for example
                                        "http://myproxy:3128" or
                                        "socks5://myproxy:8080"
  --save-session                        Whether to save the Playwright MCP
                                        session into the output directory.
  --save-trace                          Whether to save the Playwright Trace of
                                        the session into the output directory.
  --save-video <size>                   Whether to save the video of the session
                                        into the output directory. For example
                                        "--save-video=800x600"
  --secrets <path>                      path to a file containing secrets in the
                                        dotenv format
  --shared-browser-context              reuse the same browser context between
                                        all connected HTTP clients.
  --storage-state <path>                path to the storage state file for
                                        isolated sessions.
  --test-id-attribute <attribute>       specify the attribute to use for test
                                        ids, defaults to "data-testid"
  --timeout-action <timeout>            specify action timeout in milliseconds,
                                        defaults to 5000ms
  --timeout-navigation <timeout>        specify navigation timeout in
                                        milliseconds, defaults to 60000ms
  --user-agent <ua string>              specify user agent string
  --user-data-dir <path>                path to the user data directory. If not
                                        specified, a temporary directory will be
                                        created.
  --viewport-size <size>                specify browser viewport size in pixels,
                                        for example "1280x720"

用户配置文件

您可以像使用常规浏览器（默认设置）一样，使用持久配置文件运行 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": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state={path/to/storage.json}"
      ]
    }
  }
}

浏览器扩展

Playwright MCP Chrome 扩展程序允许您连接到现有的浏览器标签页，并利用您的登录会话和浏览器状态。详见 扩展/README.md 用于安装和设置说明。

配置文件

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

npx @playwright/mcp@latest --config path/to/config.json
Configuration file schema 
{
  // Browser configuration
  browser?: {
    // Browser type to use (chromium, firefox, or webkit)
    browserName?: 'chromium' | 'firefox' | 'webkit';

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

    // Path to user data directory for browser profile persistence
    userDataDir?: string;

    // Browser launch options (see Playwright docs)
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // Browser channel (e.g. 'chrome')
      headless?: boolean;      // Run in headless mode
      executablePath?: string; // Path to browser executable
      // ... other Playwright launch options
    };

    // Browser context options
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... other Playwright context options
    };

    // CDP endpoint for connecting to existing browser
    cdpEndpoint?: string;

    // Remote Playwright server endpoint
    remoteEndpoint?: string;
  },

  // Server configuration
  server?: {
    port?: number;  // Port to listen on
    host?: string;  // Host to bind to (default: localhost)
  },

  // List of additional capabilities
  capabilities?: Array<
    'tabs' |    // Tab management
    'install' | // Browser installation
    'pdf' |     // PDF generation
    'vision' |  // Coordinate-based interactions
  >;

  // Directory for output files
  outputDir?: string;

  // Network configuration
  network?: {
    // List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
    allowedOrigins?: string[];

    // List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
    blockedOrigins?: string[];
  };
 
  /**
   * Whether to send image responses to the client. Can be "allow" or "omit". 
   * Defaults to "allow".
   */
  imageResponses?: 'allow' | 'omit';
}

独立MCP服务器

当在没有显示器的系统上或从集成开发环境（IDE）的工作者进程中运行无头浏览器时， 在设置了DISPLAY环境变量的环境中运行MCP服务器，并传递（相关参数或设置） --port 启用HTTP传输的标志。

npx @playwright/mcp@latest --port 8931

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

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

注： 目前，Docker 实现仅支持无头模式的 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 \
  cli.js --headless --browser chromium --no-sandbox --port 8931

服务器将在主机端口上监听 8931 并且可以被任何MCP客户端访问。

你可以自己构建Docker镜像。

docker build -t mcr.microsoft.com/playwright/mcp .
Programmatic usage 
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);

  // ...
});

工具

Core automation
  • 浏览器点击
    • 标题：点击
    • 描述：在网页上执行点击操作
    • 参数：
      • element (字符串)：用于获取与元素交互权限的可读元素描述
      • ref (字符串)：来自页面快照的确切目标元素引用
      • doubleClick (布尔值，可选)：是否执行双击而非单击
      • button （字符串，可选）：要点击的按钮，默认为左键
      • modifiers (数组，可选)：要按下的修饰键
    • 只读： 错误的
  • 浏览器关闭
    • 标题：关闭浏览器
    • 描述：关闭页面
    • 参数：无
    • 只读： 错误的
  • 浏览器控制台消息
    • 标题：获取控制台消息
    • 描述：返回所有控制台消息
    • 参数：
      • onlyErrors (布尔值，可选)：仅返回错误信息
    • 只读： 真
  • 浏览器拖动
    • 标题：拖动鼠标
    • 描述：在两个元素之间执行拖放操作
    • 参数：
      • startElement （字符串）：用于获取与元素交互权限的、可读的人类元素来源描述
      • startRef (字符串)：来自页面快照的精确源元素引用
      • endElement （字符串）：用于获取与元素交互权限的人类可读的目标元素描述
      • endRef (字符串)：来自页面快照的精确目标元素引用
    • 只读： 错误的
  • 浏览器评估
    • 标题：评估JavaScript
    • 描述：在页面或元素上评估JavaScript表达式
    • 参数：
      • function (字符串): () => { /* 代码 / } 或 (元素) => { / 当元素提供时，代码 */ }
      • element （字符串，可选）：用于获取与元素交互权限的人类可读的元素描述
      • ref (字符串，可选)：来自页面快照的确切目标元素引用
    • 只读： 错误的
  • 浏览器文件上传
    • 标题：上传文件
    • 描述：上传一个或多个文件
    • 参数：
      • paths （数组，可选）：要上传的文件的绝对路径。可以是单个文件或多个文件。如果省略，则文件选择器将被取消。
    • 只读： 错误的
  • 浏览器填写表单
    • 标题：填写表格
    • 描述：填写多个表单字段
    • 参数：
      • fields (数组)：需填写的字段
    • 只读： 错误的
  • 处理浏览器对话框
    • 标题：处理对话框
    • 描述：处理对话框
    • 参数：
      • accept (布尔值)：是否接受对话框。
      • promptText （字符串，可选）：在出现提示对话框时，提示信息的文本。
    • 只读： 错误的
  • 浏览器悬停
    • 标题：悬停鼠标
    • 描述：将鼠标悬停在页面上的元素上
    • 参数：
      • element （字符串）：用于获取与元素交互权限的可读元素描述
      • ref (字符串)：来自页面快照的精确目标元素引用
    • 只读： 错误的
  • 浏览器导航
    • 标题：导航至URL
    • 描述：导航到一个URL
    • 参数：
      • url （字符串）：要导航到的URL
    • 只读： 错误的
  • 浏览器返回上一页
    • 标题：回去
    • 描述：返回上一页
    • 参数：无
    • 只读： 错误的
  • 浏览器网络请求
    • 标题：列出网络请求
    • 描述：返回自页面加载以来的所有网络请求
    • 参数：无
    • 只读： 真
  • 按下浏览器按键
    • 标题：按任意键
    • 描述：按下键盘上的一个键
    • 参数：
      • key （字符串）：要按下的键的名称或要生成的字符，例如 ArrowLeft 或者 a
    • 只读： 错误的
  • 浏览器调整大小
    • 标题：调整浏览器窗口大小
    • 描述：调整浏览器窗口大小
    • 参数：
      • width （数字）：浏览器窗口的宽度
      • height (数字)：浏览器窗口的高度
    • 只读： 错误的
  • 选择浏览器选项
    • 标题：选择选项
    • 描述：在下拉菜单中选择一个选项
    • 参数：
      • element （字符串）：用于获取与该元素交互权限的可读元素描述
      • ref （字符串）：来自页面快照的精确目标元素引用
      • values （数组）：下拉菜单中要选择的值的数组。这可以是一个值或多个值。
    • 只读： 错误的
  • 浏览器快照
    • 标题：页面快照
    • 描述：捕获当前页面的无障碍性快照，这比截图更好
    • 参数：无
    • 只读： 真
  • 浏览器截图
    • 标题：截屏
    • 描述：对当前页面进行截图。您不能基于截图执行操作，请使用 browser_snapshot 来执行操作。
    • 参数：
      • type （字符串，可选）：截图的图像格式。默认为 png。
      • filename (字符串，可选)：保存截图的文件名。默认为 page-{timestamp}.{png|jpeg} 如未指定，建议使用相对文件名以保持在输出目录内。
      • element （字符串，可选）：用于获取对元素进行截图权限的可读描述。如果未提供，则截图整个视口。如果提供了元素，则必须同时提供引用（ref）。
      • ref （字符串，可选）：页面快照中的精确目标元素引用。如果未提供，则将对视口进行截图。如果提供了引用（ref），则也必须提供元素（element）。
      • fullPage （布尔值，可选）：当设为true时，将截取整个可滚动页面的截图，而不是当前可见的视口截图。不能与元素截图功能同时使用。
    • 只读： 真
  • 浏览器类型
    • 标题：输入文本
    • 描述：在可编辑元素中输入文本
    • 参数：
      • element (字符串)：用于获取与该元素交互权限的可读元素描述
      • ref (字符串)：来自页面快照的确切目标元素引用
      • text （字符串）：要输入到元素中的文本
      • submit (布尔值，可选)：是否提交输入的文本（输入后按回车键）
      • slowly (布尔值，可选)：是否每次输入一个字符。这对于触发页面中的按键处理程序很有用。默认情况下，整个文本会一次性填入。
    • 只读： 错误的
  • 等待浏览器（操作/加载）
    • 标题：等待
    • 描述：等待文本出现或消失，或等待指定时间过去
    • 参数：
      • time （数字，可选）：等待的秒数
      • text (字符串，可选)：等待的文本
      • textGone (字符串，可选)：等待消失的文本
    • 只读： 错误的
Tab management
  • 浏览器标签页
    • 标题：管理标签页
    • 描述：列出、创建、关闭或选择浏览器标签页。
    • 参数：
      • action （字符串）：要执行的操作
      • index （数字，可选）：标签索引，用于关闭/选择。若省略关闭时的索引，则关闭当前标签。
    • 只读： 错误的
Browser installation
  • 浏览器安装
    • 标题：安装配置文件中指定的浏览器
    • 描述：安装配置中指定的浏览器。如果遇到浏览器未安装的错误，请调用此操作。
    • 参数：无
    • 只读： 错误的
Coordinate-based (opt-in via --caps=vision)
  • 浏览器鼠标点击坐标（xy）
    • 标题：点击
    • 描述：在指定位置点击鼠标左键
    • 参数：
      • element （字符串）：用于获取与元素交互权限的人类可读元素描述
      • x （数字）：X坐标
      • y (数字)：Y坐标
    • 只读： 错误的
  • 浏览器鼠标拖动坐标（xy）
    • 标题：拖动鼠标
    • 描述：按住鼠标左键拖动到指定位置
    • 参数：
      • element (字符串)：用于获取与元素交互权限的人类可读元素描述
      • startX （数字）：起始X坐标
      • startY （数字）：起始Y坐标
      • endX (数字)：结束X坐标
      • endY (数字)：结束Y坐标
    • 只读： 错误的
  • 浏览器鼠标移动到指定坐标
    • 标题：移动鼠标
    • 描述：将鼠标移动到指定位置
    • 参数：
      • element （字符串）：用于获取与元素交互权限的可读元素描述
      • x (数字)：X坐标
      • y (数字)：Y坐标
    • 只读： 错误的
PDF generation (opt-in via --caps=pdf)
  • 浏览器保存PDF
    • 标题：另存为PDF
    • 描述：将页面保存为PDF文件
    • 参数：
      • filename (字符串，可选)：保存PDF文件的文件名。默认为 page-{timestamp}.pdf 如果未指定，则建议使用相对文件名以保持在输出目录内。
    • 只读： 真
Test assertions (opt-in via --caps=testing)
  • 浏览器生成定位器
    • 标题：为元素创建定位器
    • 描述：为给定元素生成定位器，以便在测试中使用
    • 参数：
      • element (字符串)：用于获取与元素交互权限的人类可读元素描述
      • ref (字符串)：来自页面快照的确切目标元素引用
    • 只读： 真
  • 浏览器验证元素可见
    • 标题：验证元素可见性
    • 描述：验证元素在页面上可见
    • 参数：
      • role (字符串)：元素的角色。在快照中可以这样找到： - {ROLE} "Accessible Name":
      • accessibleName (字符串)：元素的ACCESSIBLE_NAME。可以在快照中这样找到它： - role "{ACCESSIBLE_NAME}"
    • 只读： 错误的
  • 浏览器验证列表可见
    • 标题：验证列表可见
    • 描述：验证列表在页面上可见
    • 参数：
      • element （字符串）：可读的列表描述
      • ref (字符串)：指向列表的确切目标元素引用
      • items (数组)：待验证的项目
    • 只读： 错误的
  • 浏览器验证文本可见性
    • 标题：验证可见文本
    • 描述：验证文本是否在页面上可见。如果可能，建议使用浏览器验证元素可见性功能。
    • 参数：
      • text (字符串)：要验证的文本。可以在快照中这样找到： - role "Accessible Name": {TEXT} 或者像这样： - text: {TEXT}
    • 只读： 错误的
  • 浏览器验证值
    • 标题：验证值
    • 描述：验证元素值
    • 参数：
      • type (字符串)：元素的类型
      • element (字符串)：可读的人类元素描述
      • ref （字符串）：指向元素的确切目标元素引用
      • value (字符串)：要验证的值。对于复选框，使用“true”或“false”。
    • 只读： 错误的
Tracing (opt-in via --caps=tracing)
  • 浏览器开始追踪
    • 标题：开始追踪
    • 描述：开始记录追踪
    • 参数：无
    • 只读： 真
  • 停止浏览器追踪
    • 标题：停止追踪
    • 描述：停止跟踪记录
    • 参数：无
    • 只读： 真

相关 MCP