使用说明

剧作家MCP

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

主要特点

快速轻便。使用Playwright的可访问性树，而不是基于像素的输入。
LLM友好无需视觉模型，仅基于结构化数据进行操作。
确定性工具应用避免了基于屏幕截图的方法中常见的歧义。

需求

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

入门

首先，在客户端安装Playwright MCP服务器。典型的配置如下：

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

Install in VS Code

您还可以使用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代理。

Install in Cursor

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

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

Install in Windsurf

关注Windsuff MCP 文档.使用以下配置：

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

Install in Claude Desktop

遵循MCP安装指南，使用以下配置：

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

配置

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

> npx @playwright/mcp@latest --help
  --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 capabilities to enable,
                               possible values: tabs, pdf, history, wait, files,
                               install. Default is all.
  --cdp-endpoint <endpoint>    CDP endpoint to connect to.
  --config <path>              path to the configuration file.
  --device <device>            device to emulate, for example: "iPhone 15"
  --executable-path <path>     path to the browser executable.
  --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
  --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", "omit", or "auto". Defaults to
                               "auto", which sends images if the client can
                               display them.
  --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-trace                 Whether to save the Playwright Trace of the
                               session into the output directory.
  --storage-state <path>       path to the storage state file for isolated
                               sessions.
  --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 "1280, 720"
  --vision                     Run server that uses screenshots (Aria snapshots
                               are used by default)

用户档案

您可以像常规浏览器（默认）一样使用持久配置文件运行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服务器可以使用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 enabled capabilities
  capabilities?: Array<
    'core' |    // Core browser automation
    'tabs' |    // Tab management
    'pdf' |     // PDF generation
    'history' | // Browser history
    'wait' |    // Wait utilities
    'files' |   // File handling
    'install' | // Browser installation
    'testing'   // Testing
  >;

  // Enable vision mode (screenshots instead of accessibility snapshots)
  vision?: boolean;

  // 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[];
  };
 
  /**
   * Do not send image responses to the client.
   */
  noImageResponses?: boolean;
}

独立MCP服务器

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

npx @playwright/mcp@latest --port 8931

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

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

Docker

注： Docker实现目前只支持无头铬。

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/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);

  // ...
});

工具

这些工具有两种模式：

快照模式 （默认）：使用可访问性快照以获得更好的性能和可靠性
视觉模式：使用屏幕截图进行基于视觉的交互

要使用视觉模式，请添加 --vision 启动服务器时标记：

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

视觉模式与能够使用以下方式与元素交互的计算机使用模型配合使用效果最佳 X Y坐标空间，基于提供的屏幕截图。

Interactions

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

浏览器点击
- 标题：点击
- 描述：在网页上执行点击操作
- 参数：
  - element （string）：人类可读的元素描述，用于获得与元素交互的权限
  - ref （string）：页面快照中的精确目标元素引用
- 只读： 错误的

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

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

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

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

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

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

浏览器文件上传
- 标题：上传文件
- 说明：上传一个或多个文件
- 参数：
  - paths （array）：要上传的文件的绝对路径。可以是单个文件或多个文件。
- 只读： 错误的

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

Navigation

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

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

浏览器导航转发
- 标题：前进
- 说明：转到下一页
- 参数：无
- 只读：真

Resources

browser_take_screenshot
- 标题：截图
- 描述：截取当前页面的屏幕截图。您无法根据屏幕截图执行操作，请使用browser_snapshot进行操作。
- 参数：
  - raw （boolean，可选）：是否返回不压缩（PNG格式）。默认值为false，返回JPEG图像。
  - filename （string，可选）：保存截图的文件名。默认为 page-{timestamp}.{png|jpeg} 如果没有指定。
  - element （string，可选）：人类可读的元素描述，用于获得对元素进行截图的权限。如果没有提供，将对视口进行截图。如果提供了元素，也必须提供ref。
  - ref （string，可选）：页面快照中的精确目标元素引用。如果没有提供，将对视口进行截图。若提供了ref，则也必须提供元素。
- 只读：真

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

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

browser_console_消息
- 标题：获取控制台消息
- 说明：返回所有控制台消息
- 参数：无
- 只读：真

Utilities

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

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

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

Tabs

browser_tab_list
- 标题：列表选项卡
- 说明：列出浏览器选项卡
- 参数：无
- 只读：真

browser_tab_new
- 标题：打开新选项卡
- 说明：打开一个新选项卡
- 参数：
  - url （字符串，可选）：在新选项卡中导航到的URL。如果没有提供，新选项卡将为空。
- 只读：真

浏览器选项卡选择
- 标题：选择选项卡
- 说明：按索引选择选项卡
- 参数：
  - index （数字）：要选择的选项卡的索引
- 只读：真

browser_tab_close
- 标题：关闭选项卡
- 说明：关闭选项卡
- 参数：
  - index （数字，可选）：要关闭的选项卡的索引。如果未提供，则关闭当前选项卡。
- 只读： 错误的

Testing

浏览器生成剧作家测试
- 标题：生成剧作家测试
- 描述：为给定场景生成剧作家测试
- 参数：
  - name （string）：测试的名称
  - description （string）：测试的描述
  - steps （array）：测试步骤
- 只读：真

Vision mode

浏览器屏幕捕获
- 标题：截图
- 描述：截取当前页面的屏幕截图
- 参数：无
- 只读：真

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

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

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

浏览器屏幕类型
- 标题：键入文本
- 说明：键入文本
- 参数：
  - text （string）：要在元素中键入的文本
  - submit （布尔值，可选）：是否提交输入的文本（之后按Enter键）
- 只读： 错误的

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

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

浏览器文件上传
- 标题：上传文件
- 说明：上传一个或多个文件
- 参数：
  - paths （array）：要上传的文件的绝对路径。可以是单个文件或多个文件。
- 只读： 错误的

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

使用说明

剧作家MCP

主要特点

需求

入门

配置

用户档案

配置文件

独立MCP服务器

工具

相关 MCP

浏览器自动化MCP服务

浏览器自动化MCP服务器

网页内容抓取服务

Playwright浏览器自动化服务器

iOS模拟器交互服务器

网页抓取与搜索MCP服务器