使用说明

剧作家MCP

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

主要特点

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

用例

Web导航和表单填写
从结构化内容中提取数据
LLM驱动的自动化测试
代理的通用浏览器交互

配置示例

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

在VS代码中安装

您可以使用VS Code CLI安装Playwright MCP服务器：

# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@hyhfish/mcp-hyh@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>：以逗号分隔的要启用的功能列表，可能的值：选项卡、pdf、历史记录、等待、文件、安装。默认值为全部。
--cdp-endpoint <endpoint>：要连接的CDP终结点
--executable-path <path>：浏览器可执行文件的路径
--headless：在无头模式下运行浏览器（默认情况下为无头模式）
--device：模拟移动设备
--user-data-dir <path>：用户数据目录的路径
--port <port>：监听SSE运输的港口
--host <host>：将服务器绑定到的主机。默认值为localhost。使用0.0.0.0绑定到所有接口。
--allowed-origins <origins>：以分号分隔的源列表，允许浏览器请求。默认设置为允许所有。起源匹配两者 --allowed-origins 和 --blocked-origins 将被封锁。
--blocked-origins <origins>：以分号分隔的源列表，用于阻止浏览器请求。起源匹配两者 --allowed-origins 和 --blocked-origins 将被封锁。
--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;

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

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

npx @hyhfish/mcp-hyh@latest --config path/to/config.json

在Linux上运行

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

npx @hyhfish/mcp-hyh@latest --port 8931

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

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

码头工人

注： 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 .

程序化使用

import http from 'http';

import { createServer } from '@hyhfish/mcp-hyh';
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": [
        "@hyhfish/mcp-hyh@latest",
        "--vision"
      ]
    }
  }
}

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

基于快照的交互

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

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

基于视觉的交互

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

浏览器_屏幕_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_tab_list
- 标题：列表选项卡
- 说明：列出浏览器选项卡
- 参数：无
- 只读：真

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

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

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

功能增强: browser_navigate 命令的 userDataDir 参数是在微软原始 Playwright MCP 项目基础上增强的功能。此参数允许在导航过程中动态切换浏览器用户配置文件目录，无需重启整个服务。当指定此参数时，当前浏览器会关闭并使用新的用户数据目录重新启动。

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

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

键盘

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

控制台

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

文件和媒体

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

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

公用事业

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

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

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

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

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

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

测试

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

使用说明

剧作家MCP

主要特点

用例

配置示例

目录

在VS代码中安装

命令行

用户档案

配置文件

在Linux上运行

码头工人

程序化使用

刀具模式

基于快照的交互

基于视觉的交互

选项卡管理

导航

键盘

控制台

文件和媒体

公用事业

测试

相关 MCP

浏览器自动化MCP服务

浏览器自动化MCP服务器

网页内容抓取服务

Playwright浏览器自动化服务器

iOS模拟器交互服务器

搜索引擎集成服务器