使用说明

剧作家MCP

一种模型上下文协议（MCP）服务器，使用以下方式提供浏览器自动化功能剧作家此服务器使LLM能够通过结构化的可访问性快照与网页交互，从而绕过了对屏幕截图或视觉优化模型的需要。

主要特点

快速轻便。使用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 CLI添加Playwright MCP服务器：

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

或者，创建或编辑配置文件 ~/.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"]}'

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

Warp

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

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

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

Windsurf

关注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实现目前只支持无头铬。

{
  "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 （string）：人类可读的元素描述，用于获得与元素交互的权限
  - ref （string）：页面快照中的精确目标元素引用
  - doubleClick （布尔值，可选）：是否执行双击而不是单击
  - button （字符串，可选）：点击按钮，默认为左侧
  - modifiers （数组，可选）：按修改键
- 只读： 错误的

浏览器_关闭
- 标题：关闭浏览器
- 说明：关闭页面
- 参数：无
- 只读： 错误的

browser_console_消息
- 标题：获取控制台消息
- 说明：返回所有控制台消息
- 参数：
  - onlyErrors （布尔值，可选）：仅返回错误消息
- 只读：真

browser_drag
- 标题：拖动鼠标
- 说明：在两个元素之间执行拖放操作
- 参数：
  - startElement （string）：人类可读的源元素描述，用于获得与元素交互的权限
  - startRef （string）：页面快照中的精确源元素引用
  - endElement （string）：人类可读的目标元素描述，用于获得与元素交互的权限
  - endRef （string）：页面快照中的精确目标元素引用
- 只读： 错误的

浏览器_评估
- 标题：评估JavaScript
- 描述：在页面或元素上计算JavaScript表达式
- 参数：
  - function （string）：（）=>{/*代码 /}或（元素）=>{/ 提供元素时的代码*/}
  - element （string，可选）：人类可读的元素描述，用于获得与元素交互的权限
  - ref （string，可选）：页面快照中的精确目标元素引用
- 只读： 错误的

浏览器文件上传
- 标题：上传文件
- 说明：上传一个或多个文件
- 参数：
  - paths （array，可选）：要上传的文件的绝对路径。可以是单个文件或多个文件。如果省略，文件选择器将被取消。
- 只读： 错误的

browser_fill_form
- 标题：填写表格
- 说明：填写多个表单字段
- 参数：
  - fields （数组）：要填写的字段
- 只读： 错误的

浏览器处理对话框
- 标题：处理对话框
- 描述：处理对话框
- 参数：
  - accept （boolean）：是否接受对话。
  - promptText （string，可选）：提示对话框中的提示文本。
- 只读： 错误的

浏览器切换
- 标题：鼠标悬停
- 描述：将鼠标悬停在页面上的元素上
- 参数：
  - element （string）：人类可读的元素描述，用于获得与元素交互的权限
  - ref （string）：页面快照中的精确目标元素引用
- 只读： 错误的

浏览器导航
- 标题：导航到URL
- 描述：导航到URL
- 参数：
  - url （string）：要导航到的URL
- 只读： 错误的

浏览器导航返回
- 标题：返回
- 说明：返回上一页
- 参数：无
- 只读： 错误的

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

browser_press_key
- 标题：按键
- 说明：按键盘上的一个键
- 参数：
  - key （string）：要按的键的名称或要生成的字符，例如 ArrowLeft 或 a
- 只读： 错误的

浏览器大小
- 标题：调整浏览器窗口大小
- 说明：调整浏览器窗口大小
- 参数：
  - width （数字）：浏览器窗口的宽度
  - height （数字）：浏览器窗口的高度
- 只读： 错误的

浏览器选择选项
- 标题：选择选项
- 说明：在下拉列表中选择一个选项
- 参数：
  - element （string）：人类可读的元素描述，用于获得与元素交互的权限
  - ref （string）：页面快照中的精确目标元素引用
  - values （array）：在下拉列表中选择的值数组。这可以是单个值或多个值。
- 只读： 错误的

浏览器快照
- 标题：页面快照
- 描述：捕获当前页面的可访问性快照，这比截图更好
- 参数：无
- 只读：真

browser_take_screenshot
- 标题：截图
- 描述：截取当前页面的屏幕截图。您无法根据屏幕截图执行操作，请使用browser_snapshot进行操作。
- 参数：
  - type （字符串，可选）：屏幕截图的图像格式。默认值为png。
  - filename （string，可选）：保存截图的文件名。默认为 page-{timestamp}.{png|jpeg} 如果没有指定。希望相对文件名保留在输出目录中。
  - element （string，可选）：人类可读的元素描述，用于获得对元素进行截图的权限。如果没有提供，将对视口进行截图。如果提供了元素，也必须提供ref。
  - ref （string，可选）：页面快照中的精确目标元素引用。如果没有提供，将对视口进行截图。若提供了ref，则也必须提供元素。
  - fullPage （boolean，可选）：当为true时，会截取整个可滚动页面的屏幕截图，而不是当前可见的视口。不能与元素截图一起使用。
- 只读：真

浏览器类型
- 标题：键入文本
- 说明：在可编辑元素中键入文本
- 参数：
  - element （string）：人类可读的元素描述，用于获得与元素交互的权限
  - ref （string）：页面快照中的精确目标元素引用
  - text （string）：要在元素中键入的文本
  - submit （布尔值，可选）：是否提交输入的文本（之后按Enter键）
  - slowly （boolean，可选）：是否一次键入一个字符。可用于触发页面中的密钥处理程序。默认情况下，一次填写整个文本。
- 只读： 错误的

浏览器等待
- 标题：等待
- 描述：等待文本出现或消失或经过指定时间
- 参数：
  - time （数字，可选）：等待时间（秒）
  - text （string，可选）：等待的文本
  - textGone （string，可选）：等待消失的文本
- 只读： 错误的

Tab management

浏览器标签
- 标题：管理选项卡
- 说明：列出、创建、关闭或选择浏览器选项卡。
- 参数：
  - action （string）：要执行的操作
  - index （数字，可选）：选项卡索引，用于关闭/选择。如果省略关闭，则关闭当前选项卡。
- 只读： 错误的

Browser installation

浏览器安装
- 标题：安装配置中指定的浏览器
- 说明：安装配置中指定的浏览器。如果您收到浏览器未安装的错误，请调用此命令。
- 参数：无
- 只读： 错误的

Coordinate-based (opt-in via --caps=vision)

浏览器_主页_点击_xy
- 标题：点击
- 说明：在给定位置单击鼠标左键
- 参数：
  - element （string）：人类可读的元素描述，用于获得与元素交互的权限
  - x （数字）：X坐标
  - y （数字）：Y坐标
- 只读： 错误的

浏览器_主页_拖动_xy
- 标题：拖动鼠标
- 说明：将鼠标左键拖动到给定位置
- 参数：
  - element （string）：人类可读的元素描述，用于获得与元素交互的权限
  - startX （数字）：开始X坐标
  - startY （数字）：开始Y坐标
  - endX （数字）：结束X坐标
  - endY （数字）：结束Y坐标
- 只读： 错误的

浏览器_家庭_移动_xy
- 标题：移动鼠标
- 说明：将鼠标移动到给定位置
- 参数：
  - element （string）：人类可读的元素描述，用于获得与元素交互的权限
  - x （数字）：X坐标
  - y （数字）：Y坐标
- 只读： 错误的

PDF generation (opt-in via --caps=pdf)

浏览器_pdf_save
- 标题：另存为PDF
- 说明：将页面另存为PDF
- 参数：
  - filename （字符串，可选）：用于保存pdf的文件名。默认为 page-{timestamp}.pdf 如果没有指定。希望相对文件名保留在输出目录中。
- 只读：真

Test assertions (opt-in via --caps=testing)

浏览器生成定位器
- 标题：为元素创建定位器
- 描述：为测试中使用的给定元素生成定位器
- 参数：
  - element （string）：人类可读的元素描述，用于获得与元素交互的权限
  - ref （string）：页面快照中的精确目标元素引用
- 只读：真

浏览器验证元素可见
- 标题：验证元素是否可见
- 说明：验证元素在页面上是否可见
- 参数：
  - role （string）：元素的角色。可以在快照中找到，如下所示： - {ROLE} "Accessible Name":
  - accessibleName （string）：元素的名称。可以在快照中找到，如下所示： - role "{ACCESSIBLE_NAME}"
- 只读： 错误的

浏览器验证列表可见
- 标题：验证列表是否可见
- 说明：验证列表在页面上是否可见
- 参数：
  - element （string）：人类可读的列表描述
  - ref （string）：指向列表的精确目标元素引用
  - items （array）：要验证的项目
- 只读： 错误的

浏览器验证文本可见
- 标题：验证文本是否可见
- 说明：验证文本在页面上是否可见。如果可能的话，首选browser_verify_element_visible。
- 参数：
  - text （string）：要验证的文本。可以在快照中找到，如下所示： - role "Accessible Name": {TEXT} 或者像这样： - text: {TEXT}
- 只读： 错误的

浏览器验证值
- 标题：验证值
- 说明：验证元素值
- 参数：
  - type （string）：元素的类型
  - element （string）：人类可读的元素描述
  - ref （string）：指向该元素的精确目标元素引用
  - value （string）：要验证的值。对于复选框，使用“true”或“false”。
- 只读： 错误的

Tracing (opt-in via --caps=tracing)

浏览器start_tracing
- 标题：开始追踪
- 说明：开始跟踪记录
- 参数：无
- 只读：真

浏览器停止跟踪
- 标题：停止追踪
- 说明：停止跟踪记录
- 参数：无
- 只读：真

使用说明

剧作家MCP

主要特点

需求

入门

单击按钮安装：

或手动安装：

单击按钮安装：

或手动安装：

单击按钮安装：

或手动安装：

单击按钮安装：

或手动安装：

配置

用户档案

配置文件

独立MCP服务器

工具

相关 MCP

浏览器自动化MCP服务

浏览器自动化MCP服务器

网页内容抓取服务

Playwright浏览器自动化服务器

iOS模拟器交互服务器

网页抓取与搜索MCP服务器