剧作家 MCP 服务器

剧作家 MCP

一个使用Playwright提供浏览器自动化功能的模型上下文协议 (MCP) 服务器。该服务器使 LLM 能够通过结构化的可访问性快照与网页进行交互，而无需使用屏幕截图或视觉调整的模型。

主要特点

快速且轻量：使用 Playwright 的可访问性树，而不是基于像素的输入。
适合法学硕士 (LLM) ：无需视觉模型，纯粹基于结构化数据运行。
确定性工具应用：避免基于屏幕截图的方法常见的歧义。

用例

网页导航和表单填写
从结构化内容中提取数据
由法学硕士 (LLM) 驱动的自动化测试
代理的通用浏览器交互

示例配置

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

在 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 代理一起使用。

命令行

Playwright MCP 服务器支持以下命令行选项：

--browser <browser> ：要使用的浏览器或 Chrome 通道。可能的值：
- chrome 、 firefox 、 webkit 、 msedge
- Chrome 渠道： chrome-beta 、 chrome-canary 、 chrome-dev
- 边缘渠道： msedge-beta 、 msedge-canary 、 msedge-dev
- 默认值： chrome
--caps <caps> ：以逗号分隔的要启用的功能列表，可能的值包括：tabs、pdf、history、wait、files、install。默认为全部。
--cdp-endpoint <endpoint> ：要连接的 CDP 端点
--executable-path <path> ：浏览器可执行文件的路径
--headless ：以无头模式运行浏览器（默认为有头模式）
--device ：模拟移动设备
--user-data-dir <path> ：用户数据目录的路径
--port <port> ：监听 SSE 传输的端口
--host <host> ：绑定服务器的主机名。默认为 localhost。使用 0.0.0.0 表示绑定到所有接口。
--vision ：运行使用屏幕截图的服务器（默认使用 Aria 快照）
--output-dir ：输出文件的目录
--config <path> ：配置文件的路径

用户个人资料

Playwright MCP 将启动带有新配置文件的浏览器，位于

- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile` on Windows
- `~/Library/Caches/ms-playwright/mcp-{channel}-profile` on macOS
- `~/.cache/ms-playwright/mcp-{channel}-profile` on Linux

所有登录信息都将存储在该配置文件中，如果您想清除离线状态，可以在会话之间将其删除。

配置文件

Playwright MCP 服务器可以使用 JSON 配置文件进行配置。完整的配置格式如下：

{
  // Browser configuration
  browser?: {
    // Browser type to use (chromium, firefox, or webkit)
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // 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;

  // Tool-specific configurations
  tools?: {
    browser_take_screenshot?: {
      // Disable base64-encoded image responses
      omitBase64?: boolean;
    }
  }
}

您可以使用--config命令行选项指定配置文件：

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

在 Linux 上运行

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

npx @playwright/mcp@latest --port 8931

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

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

Docker

注意： Docker 实现目前仅支持无头 Chromium。

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "mcp/playwright"]
    }
  }
}

您可以自己构建 Docker 镜像。

docker build -t mcp/playwright .

程序化使用

import http from 'http';

import { createServer } 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 mcpServer = await createServer({ headless: true });
  const transport = new SSEServerTransport('/messages', res);
  await mcpServer.connect(transport);

  // ...
});

工具模式

该工具有两种模式：

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

要使用 Vision 模式，请在启动服务器时添加--vision标志：

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

根据提供的屏幕截图，视觉模式最适合能够使用 XY 坐标空间与元素交互的计算机使用模型。

基于快照的交互

browser_snapshot
- 描述：捕获当前页面的可访问性快照，这比屏幕截图更好
- 参数：无
browser_click
- 描述：执行网页上的点击操作
- 参数：
  - element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
  - ref （字符串）：来自页面快照的精确目标元素引用
browser_drag
- 描述：在两个元素之间执行拖放操作
- 参数：
  - startElement （字符串）：用于获取与元素交互的权限的人类可读的源元素描述
  - startRef （字符串）：来自页面快照的精确源元素引用
  - endElement （字符串）：用于获取与元素交互的权限的人类可读的目标元素描述
  - endRef （字符串）：来自页面快照的精确目标元素引用
browser_hover
- 描述：将鼠标悬停在页面上的元素上
- 参数：
  - element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
  - ref （字符串）：来自页面快照的精确目标元素引用
浏览器类型
- 描述：在可编辑元素中输入文本
- 参数：
  - element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
  - ref （字符串）：来自页面快照的精确目标元素引用
  - text （字符串）：输入到元素中的文本
  - submit （布尔值，可选）：是否提交输入的文本（按 Enter 键后）
  - slowly （布尔值，可选）：是否一次输入一个字符。用于触发页面中的按键处理程序。默认情况下，整个文本会一次性填充。
browser_select_option
- 描述：在下拉菜单中选择一个选项
- 参数：
  - element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
  - ref （字符串）：来自页面快照的精确目标元素引用
  - values （数组）：下拉菜单中要选择的值的数组。可以是单个值，也可以是多个值。
browser_take_screenshot
- 描述：截取当前页面的屏幕截图。您无法根据屏幕截图执行任何操作，请使用 browser_snapshot 执行操作。
- 参数：
  - raw （布尔值，可选）：是否返回未压缩的图像（PNG 格式）。默认值为 false，即返回 JPEG 格式的图像。
  - element （字符串，可选）：用于获取元素截图权限的可读元素描述。若未提供，则截取视口范围的屏幕截图。若提供 element，则必须同时提供 ref。
  - ref （字符串，可选）：页面快照中目标元素的精确引用。若未提供，则屏幕截图将截取视口。若提供 ref，则必须同时提供元素。

基于视觉的交互

browser_screen_capture
- 描述：截取当前页面的屏幕截图
- 参数：无
browser_screen_move_mouse
- 描述：移动鼠标到指定位置
- 参数：
  - element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
  - x （数字）：X 坐标
  - y （数字）：Y 坐标
browser_screen_click
- 描述：单击鼠标左键
- 参数：
  - element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
  - x （数字）：X 坐标
  - y （数字）：Y 坐标
browser_screen_drag
- 描述：拖动鼠标左键
- 参数：
  - element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
  - startX （数字）：起始X坐标
  - startY （数字）：起始 Y 坐标
  - endX （数字）：结束X坐标
  - endY （数字）：结束 Y 坐标
浏览器屏幕类型
- 描述：输入文本
- 参数：
  - text （字符串）：输入到元素中的文本
  - submit （布尔值，可选）：是否提交输入的文本（按 Enter 键后）

标签管理

browser_tab_list
- 描述：列出浏览器标签页
- 参数：无
browser_tab_new
- 描述：打开新标签页
- 参数：
  - url （字符串，可选）：新标签页中导航到的 URL。如果不提供，新标签页将为空白。
browser_tab_select
- 描述：通过索引选择选项卡
- 参数：
  - index （数字）：要选择的选项卡的索引
browser_tab_close
- 描述：关闭标签页
- 参数：
  - index （数字，可选）：要关闭的标签页的索引。如果未提供，则关闭当前标签页。

键盘

browser_press_key
- 描述：按下键盘上的一个键
- 参数：
  - key （字符串）：要按下的键的名称或要生成的字符，例如ArrowLeft``a

安慰

browser_console_messages
- 描述：返回所有控制台消息
- 参数：无

文件和媒体

browser_file_upload
- 描述：上传一个或多个文件
- 参数：
  - paths （数组）：要上传的文件的绝对路径。可以是单个文件，也可以是多个文件。
browser_pdf_save
- 描述：将页面保存为 PDF
- 参数：无

实用工具

browser_close
- 描述：关闭页面
- 参数：无
browser_wait
- 描述：等待指定的时间（以秒为单位）
- 参数：
  - time （数字）：等待的时间（秒）
browser_resize
- 描述：调整浏览器窗口的大小
- 参数：
  - width （数字）：浏览器窗口的宽度
  - height （数字）：浏览器窗口的高度
浏览器安装
- 描述：安装配置中指定的浏览器。如果出现浏览器未安装的错误，请调用此函数。
- 参数：无
browser_handle_dialog
- 描述：处理对话
- 参数：
  - accept （布尔值）：是否接受对话。
  - promptText （字符串，可选）：提示对话框中的提示文本。

测试

browser_generate_playwright_test
- 描述：为给定场景生成 Playwright 测试
- 参数：
  - name （字符串）：测试的名称
  - description （字符串）：测试的描述
  - steps （数组）：测试的步骤

Playwright MCP Server

Integrations