使用说明
剧作家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"
]
}
}
}
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
关注Windsurf MCP 文档.使用以下配置:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
Install in Claude Desktop
遵循MCP安装 指南,使用以下配置:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
Install in Claude Code
使用Claude Code CLI添加Playwright MCP服务器:
claude mcp add playwright npx @playwright/mcp@latest
Install in Goose
单击按钮安装:
或手动安装:
首选 Advanced settings -> Extensions -> Add custom extension.按你的喜好命名,使用类型 STDIO,并设置 command 到 npx @playwright/mcp。单击“添加扩展名”。
Install in Qodo Gen
打开 Qodo Gen VSCode或IntelliJ中的聊天面板→ 连接更多工具→ + 添加新MCP→ 粘贴以下配置:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
点击 保存.
Install in Gemini CLI
遵循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.
--browser-agent <endpoint> Use browser agent (experimental).
--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[];
};
/**
* Whether to send image responses to the client. Can be "allow", "omit", or "auto".
* Defaults to "auto", images are omitted for Cursor clients and sent for all other clients.
*/
imageResponses?: 'allow' | 'omit' | 'auto';
}
独立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.sever.connect(transport);
// ...
});
工具
这些工具有两种模式:
- 快照模式 (默认):使用可访问性快照以获得更好的性能和可靠性
- 视觉模式:使用屏幕截图进行基于视觉的交互
要使用视觉模式,请添加 --vision 启动服务器时标记:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--vision"
]
}
}
}
视觉模式与能够使用以下方式与元素交互的计算机使用模型配合使用效果最佳 X Y坐标空间,基于提供的屏幕截图。
Interactions
- 浏览器快照
- 标题:页面快照
- 描述:捕获当前页面的可访问性快照,这比截图更好
- 参数:无
- 只读: 真
- 浏览器点击
- 标题:点击
- 描述:在网页上执行点击操作
- 参数:
element(string):人类可读的元素描述,用于获得与元素交互的权限ref(string):页面快照中的精确目标元素引用doubleClick(布尔值,可选):是否执行双击而不是单击
- 只读: 错误的
- 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,可选):提示对话框中的提示文本。
- 只读: 错误的