配置

🌐 Configuration

有头模式和无头模式

🌐 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"]

视口大小

🌐 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.

配置文件

🌐 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;
    initPage?: string[];
    initScript?: string[];
  };
  extension?: boolean;
  server?: {
    port?: number;
    host?: string;
    allowedHosts?: string[];
  };
  saveVideo?: { width: number; height: number };
  capabilities?: ('core' | 'core-navigation' | 'core-tabs' | 'core-input'
    | 'network' | 'storage' | 'testing' | 'vision' | 'pdf' | 'devtools')[];
  secrets?: Record<string, string>;
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  snapshot?: { mode?: 'full' | 'none' };
  imageResponses?: 'allow' | 'omit';
  outputDir?: string;
  outputMode?: 'file' | 'stdout';
  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
  };
  allowUnrestrictedFileAccess?: boolean;
  codegen?: 'typescript' | 'none';
}

初始化脚本

🌐 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>	使用的浏览器	PLAYWRIGHT_MCP_BROWSER
--headless	无头运行	PLAYWRIGHT_MCP_HEADLESS
--caps <caps>	启用功能（用逗号分隔）	PLAYWRIGHT_MCP_CAPS
--config <path>	配置文件路径	PLAYWRIGHT_MCP_CONFIG
--isolated	内存中的配置文件	PLAYWRIGHT_MCP_ISOLATED
--extension	通过浏览器扩展连接	PLAYWRIGHT_MCP_EXTENSION
--user-data-dir <path>	自定义配置文件目录	PLAYWRIGHT_MCP_USER_DATA_DIR
--storage-state <path>	初始存储状态	PLAYWRIGHT_MCP_STORAGE_STATE
--port <port>	HTTP 传输端口	PLAYWRIGHT_MCP_PORT
--host <host>	服务器主机	PLAYWRIGHT_MCP_HOST
--device <device>	模拟设备	PLAYWRIGHT_MCP_DEVICE
--executable-path <path>	自定义浏览器可执行文件	PLAYWRIGHT_MCP_EXECUTABLE_PATH
--viewport-size <size>	视口（例如，“1280x720”）	PLAYWRIGHT_MCP_VIEWPORT_SIZE
--proxy-server <url>	代理服务器	PLAYWRIGHT_MCP_PROXY_SERVER
--proxy-bypass <hosts>	绕过代理	PLAYWRIGHT_MCP_PROXY_BYPASS
--user-agent <ua>	自定义用户代理	PLAYWRIGHT_MCP_USER_AGENT
--ignore-https-errors	忽略 HTTPS 错误	PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS
--timeout-action <ms>	操作超时 (5000)	PLAYWRIGHT_MCP_TIMEOUT_ACTION
--timeout-navigation <ms>	导航超时 (60000)	PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION
--console-level <level>	控制台等级	PLAYWRIGHT_MCP_CONSOLE_LEVEL
--test-id-attribute <attr>	测试 ID 属性	PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE
--codegen <lang>	代码生成语言	PLAYWRIGHT_MCP_CODEGEN
--init-page <path>	页面初始化 TypeScript	PLAYWRIGHT_MCP_INIT_PAGE
--init-script <path>	页面初始化 JavaScript	PLAYWRIGHT_MCP_INIT_SCRIPT
--blocked-origins <origins>	阻止来源	PLAYWRIGHT_MCP_BLOCKED_ORIGINS
--allowed-origins <origins>	允许来源	PLAYWRIGHT_MCP_ALLOWED_ORIGINS
--grant-permissions <perms>	浏览器权限	PLAYWRIGHT_MCP_GRANT_PERMISSIONS
--block-service-workers	阻止服务工作者	PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS
--no-sandbox	禁用沙箱	PLAYWRIGHT_MCP_NO_SANDBOX
--output-dir <path>	输出目录	PLAYWRIGHT_MCP_OUTPUT_DIR
--save-session	保存会话数据	PLAYWRIGHT_MCP_SAVE_SESSION
--save-video <size>	自动录制视频（例如，“800x600”）	PLAYWRIGHT_MCP_SAVE_VIDEO
--secrets <path>	密钥文件（dotenv）	PLAYWRIGHT_MCP_SECRETS_FILE