配置

🌐 Configuration

可以通过三种方式提供选项，优先级依次增加：配置文件、环境变量和命令行参数。

🌐 Options can be supplied three ways, in increasing order of precedence: a config file, environment variables, and command-line arguments.

有头模式和无头模式

🌐 Headed and headless mode

默认情况下，Playwright MCP 会以有界面模式运行浏览器，这样你可以看到发生了什么。要以无头模式运行：

🌐 By default, Playwright MCP runs the browser in headed mode so you can see what's happening. To run headless:

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

浏览器选择

🌐 Browser selection

["@playwright/mcp@latest", "--browser=firefox"]

值	浏览器
chrome	谷歌浏览器（默认）
firefox	火狐浏览器
webkit	WebKit（Safari 引擎）
msedge	微软 Edge

设备模拟

🌐 Device emulation

["@playwright/mcp@latest", "--device=iPhone 15"]

--mobile 模拟通用移动设备——Chromium 上的 Pixel 10，WebKit 上的 iPhone 17。

视口大小

🌐 Viewport size

["@playwright/mcp@latest", "--viewport-size=1280x720"]

代理

🌐 Proxy

["@playwright/mcp@latest", "--proxy-server=http://myproxy:3128", "--proxy-bypass=localhost,*.internal.com"]

独立 HTTP 服务器

🌐 Standalone HTTP server

在没有显示器的系统上或从 IDE 工作进程运行带界面的浏览器时，请单独启动带有 HTTP 传输的 MCP 服务器：

🌐 When running a headed browser on a system without a display or from IDE worker processes, start the MCP server separately with HTTP transport:

npx @playwright/mcp@latest --port 8931

然后将你的 MCP 客户端指向 HTTP 端点：

🌐 Then point your MCP client to the HTTP endpoint:

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

使用 --host 0.0.0.0 绑定到所有接口（在容器中很有用）。使用 --shared-browser-context 在多个已连接的客户端之间共享单个浏览器上下文。

🌐 Use --host 0.0.0.0 to bind to all interfaces (useful in containers). Use --shared-browser-context to share a single browser context between multiple connected clients.

秘密

🌐 Secrets

LLM 永远不应该在工具响应中看到的值可以保存在 dotenv 文件里：

🌐 Values the LLM should never see in tool responses can be kept in a dotenv file:

npx @playwright/mcp@latest --secrets ./.secrets

工具响应中的普通文本匹配会被编辑掉，输入占位符会在页面上替代真实值。这只是为了方便使用，不是安全边界。

🌐 Matching plain text in tool responses is redacted, and typing a placeholder substitutes the real value in the page. This is a convenience, not a security boundary.

配置文件

🌐 Configuration file

对于高级设置，请使用 JSON 配置文件：

🌐 For advanced settings, use a JSON config file:

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

模式

🌐 Schema

{
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    launchOptions?: playwright.LaunchOptions;
    contextOptions?: playwright.BrowserContextOptions;
    cdpEndpoint?: string;
    cdpHeaders?: Record<string, string>;
    cdpTimeout?: number;
    remoteEndpoint?: string | playwright.ConnectOptions & { endpoint: string };
    initPage?: string[];
    initScript?: string[];
  };
  extension?: boolean;
  server?: {
    port?: number;
    host?: string;
    allowedHosts?: string[];
  };
  capabilities?: ('network' | 'storage' | 'testing' | 'vision' | 'pdf' | 'devtools' | 'config')[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;
  outputMaxSize?: number;
  console?: { level?: 'error' | 'warning' | 'info' | 'debug' };
  network?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };
  testIdAttribute?: string;
  timeouts?: {
    action?: number;      // default: 5000ms
    navigation?: number;  // default: 60000ms
    expect?: number;      // default: 5000ms
    settle?: number;      // default: 500ms
  };
  imageResponses?: 'allow' | 'omit';
  snapshot?: {
    mode?: 'full' | 'none';
    boxes?: boolean;
  };
  allowUnrestrictedFileAccess?: boolean;
  codegen?: 'typescript' | 'python' | 'java' | 'csharp' | 'none';
}

权威的模式存放在 config.d.ts。

🌐 The authoritative schema lives in config.d.ts.

初始化脚本

🌐 Init scripts

在每个页面自己的脚本之前运行代码：

🌐 Run code on every page before the page's own scripts:

{
  "browser": {
    "initScript": ["./setup.js"]
  }
}

// setup.js
window.isPlaywrightMCP = true;

初始化页面

🌐 Init page

在启动时在页面对象上运行 Playwright 代码：

🌐 Run Playwright code on the page object at startup:

{
  "browser": {
    "initPage": ["./setup-page.ts"]
  }
}

// setup-page.ts
export default async ({ page }) => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
};

所有命令行选项

🌐 All command-line options

Browser

选项	描述	环境变量
--browser <browser>	浏览器或 Chrome 渠道：chrome、firefox、webkit、msedge	PLAYWRIGHT_MCP_BROWSER
--headless	无头运行（默认有界面）	PLAYWRIGHT_MCP_HEADLESS
--executable-path <path>	浏览器可执行文件的路径	PLAYWRIGHT_MCP_EXECUTABLE_PATH
--device <device>	要模拟的设备，例如 "iPhone 15"	PLAYWRIGHT_MCP_DEVICE
--mobile	模拟一个通用的移动设备	PLAYWRIGHT_MCP_MOBILE
--viewport-size <size>	像素视口，例如 "1280x720"	PLAYWRIGHT_MCP_VIEWPORT_SIZE
--user-agent <ua>	自定义用户代理字符串	PLAYWRIGHT_MCP_USER_AGENT
--ignore-https-errors	忽略 HTTPS 错误	PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS
--proxy-server <url>	代理服务器，例如 http://myproxy:3128	PLAYWRIGHT_MCP_PROXY_SERVER
--proxy-bypass <hosts>	用逗号分隔的需要绕过代理的域名	PLAYWRIGHT_MCP_PROXY_BYPASS
--grant-permissions <perms>	要授予的权限，例如 geolocation	PLAYWRIGHT_MCP_GRANT_PERMISSIONS
--block-service-workers	阻止服务工作者	PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS
--sandbox / --no-sandbox	启用或禁用浏览器沙箱	PLAYWRIGHT_MCP_SANDBOX
--init-page <path...>	在 Playwright 页面对象上评估的 TypeScript 文件	PLAYWRIGHT_MCP_INIT_PAGE
--init-script <path...>	作为页面初始化脚本添加的 JavaScript 文件	PLAYWRIGHT_MCP_INIT_SCRIPT

个人资料和会话

🌐 Profile and session

选项	描述	环境变量
--isolated	保持浏览器配置在内存中，不保存到磁盘	PLAYWRIGHT_MCP_ISOLATED
--user-data-dir <path>	自定义配置文件目录	PLAYWRIGHT_MCP_USER_DATA_DIR
--storage-state <path>	隔离会话的初始存储状态	PLAYWRIGHT_MCP_STORAGE_STATE
--extension	通过 Playwright 浏览器扩展连接	PLAYWRIGHT_MCP_EXTENSION
--profile-dir-name <name>	要用 --extension 附加的浏览器配置目录，例如 "Profile 1"	PLAYWRIGHT_MCP_PROFILE_DIR_NAME
--cdp-endpoint <endpoint>	要连接的 CDP 端点或通道名称	PLAYWRIGHT_MCP_CDP_ENDPOINT
--cdp-header <headers...>	CDP连接请求的头信息	PLAYWRIGHT_MCP_CDP_HEADERS
--cdp-timeout <ms>	CDP 连接超时，默认值为 30000	PLAYWRIGHT_MCP_CDP_TIMEOUT
--endpoint <endpoint>	要连接的浏览器端点	—
--save-session	将 MCP 会话保存到输出目录	—

服务器

🌐 Server

选项	描述	环境变量
--port <port>	用于 HTTP 传输的监听端口	PLAYWRIGHT_MCP_PORT
--host <host>	绑定的主机，默认是 localhost	PLAYWRIGHT_MCP_HOST
--allowed-hosts <hosts...>	服务器可能服务的主机；* 可禁用检查	PLAYWRIGHT_MCP_ALLOWED_HOSTS
--shared-browser-context	在 HTTP 客户端之间复用一个浏览器上下文	—
--config <path>	配置文件路径	PLAYWRIGHT_MCP_CONFIG

工具和输出

🌐 Tools and output

选项	描述	环境变量
--caps <caps>	要启用的逗号分隔功能	PLAYWRIGHT_MCP_CAPS
--console-level <level>	控制台等级：error、warning、info、debug	PLAYWRIGHT_MCP_CONSOLE_LEVEL
--codegen <lang>	代码生成语言：typescript、python、java、csharp、none	PLAYWRIGHT_MCP_CODEGEN
--test-id-attribute <attr>	用于测试 ID 的属性，默认值为 data-testid	PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE
--snapshot-mode <mode>	full（默认）或 none	—
--snapshot-boxes	在快照中包含 [box=x,y,width,height]	—
--image-responses <mode>	allow（默认）或 omit	PLAYWRIGHT_MCP_IMAGE_RESPONSES
--output-dir <path>	自动命名输出文件的目录	PLAYWRIGHT_MCP_OUTPUT_DIR
--output-max-size <bytes>	驱逐旧输出文件的阈值	PLAYWRIGHT_MCP_OUTPUT_MAX_SIZE
--secrets <path>	dotenv 格式的秘密文件	PLAYWRIGHT_MCP_SECRETS_FILE

超时

🌐 Timeouts

选项	描述	环境变量
--timeout-action <ms>	动作超时，默认值为 5000	PLAYWRIGHT_MCP_TIMEOUT_ACTION
--timeout-navigation <ms>	导航超时，默认值为 60000	PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION
--timeout-settle <ms>	每次动作后等待触发的工作完成的时间，默认值为 500	PLAYWRIGHT_MCP_TIMEOUT_SETTLE

访问控制

🌐 Access control

选项	描述	环境变量
--allowed-origins <origins>	浏览器可能请求的以分号分隔的来源	PLAYWRIGHT_MCP_ALLOWED_ORIGINS
--blocked-origins <origins>	要阻止的以分号分隔的来源；优先评估	PLAYWRIGHT_MCP_BLOCKED_ORIGINS
--allow-unrestricted-file-access	允许工作区根目录外的文件和 file:// 导航	PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS

note

源列表和文件访问护栏是用来防止意外访问的方便防线，不是安全边界——它们不会影响重定向，而且可以被有意规避。真正的隔离要依靠客户端级别的权限。