剧作家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@latestClaude Code
使用 Claude Code CLI 添加 Playwright MCP 服务器：
claude mcp add playwright npx @playwright/mcp@latestClaude Desktop
按照MCP安装程序进行安装 指南/引导，使用上述标准配置。
Codex
创建或编辑配置文件 ~/.codex/config.toml 并补充：
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]如需更多信息，请参阅 MCP代码库文档。
Cursor
点击按钮进行安装：
[](https://cursor.com/en/install-mcp?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
或者手动安装：
首选 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 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 semicolon-separated list of origins to
allow the browser to request. Default is
to allow all.
--blocked-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 or chrome channel to use,
possible values: chrome, firefox,
webkit, msedge.
--caps comma-separated list of additional
capabilities to enable, possible values:
vision, pdf.
--cdp-endpoint CDP endpoint to connect to.
--cdp-header CDP headers to send with the connect
request, multiple can be specified.
--config
path to the configuration file.
--device device to emulate, for example: "iPhone
15"
--executable-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
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 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 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 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 to the directory for output files.
--port
port to listen on for SSE transport.
--proxy-bypass comma-separated domains to bypass proxy,
for example
".com,chromium.org,.domain.com"
--proxy-server
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 Whether to save the video of the session
into the output directory. For example
"--save-video=800x600"
--secrets
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 to the storage state file for
isolated sessions.
--test-id-attribute specify the attribute to use for test
ids, defaults to "data-testid"
--timeout-action specify action timeout in milliseconds,
defaults to 5000ms
--timeout-navigation specify navigation timeout in
milliseconds, defaults to 60000ms
--user-agent specify user agent string
--user-data-dir
path to the user data directory. If not
specified, a temporary directory will be
created.
--viewport-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.jsonConfiguration 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;
// 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)
- 浏览器开始追踪
- 标题：开始追踪 - 描述：开始记录追踪 - 参数：无 - 只读： 真
- 停止浏览器追踪
- 标题：停止追踪 - 描述：停止跟踪记录 - 参数：无 - 只读： 真