microsoft/playwright-mcp

完整文档

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

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

amp mcp add playwright -- npx @playwright/mcp@latest

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

claude mcp add playwright npx @playwright/mcp@latest

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ],
      "disabled": false
    }
  }
}

codex mcp add playwright npx "@playwright/mcp@latest"

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

/mcp add

{
  "mcpServers": {
    "playwright": {
      "type": "local",
      "command": "npx",
      "tools": [
        "*"
      ],
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

droid mcp add playwright "npx @playwright/mcp@latest"

grok mcp add playwright -- npx @playwright/mcp@latest

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

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

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

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@playwright/mcp@latest"
      ],
      "enabled": true
    }
  }
}

# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

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

# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-{workspace-hash}

macOS
~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}
Linux
~/.cache/ms-playwright/mcp-{channel}-{workspace-hash}

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state={path/to/storage.json}"
      ]
    }
  }
}

// init-script.js
window.isPlaywrightMCP = true;

Playwright MCP server 可以使用 JSON 配置文件进行配置。您可以使用 --config 命令行选项来指定该配置文件：

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

<!--- 由 update-readme.js 生成的配置 -->

{
  /**
   * The browser to use.
   */
  browser?: {
    /**
     * The type of browser to use.
     */
    browserName?: 'chromium' | 'firefox' | 'webkit';

/**
     * Keep the browser profile in memory, do not save it to disk.
     */
    isolated?: boolean;
/**
     * Path to a user data directory for browser profile persistence.
     * Temporary directory is created by default.
     */
    userDataDir?: string;
/**
     * Launch options passed to
     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
     *
     * This is useful for settings options like channel, headless, executablePath, etc.
     */
    launchOptions?: playwright.LaunchOptions;
/**
     * Context options for the browser context.
     *
     * This is useful for settings options like viewport.
     */
    contextOptions?: playwright.BrowserContextOptions;
/**
     * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
     */
    cdpEndpoint?: string;
/**
     * CDP headers to send with the connect request.
     */
    cdpHeaders?: Record<string, string>;
/**
     * Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
     */
    cdpTimeout?: number;
/**
     * Remote endpoint to connect to an existing Playwright server. May be a
     * WebSocket URL string, or a [ConnectOptions] object that mirrors the
     * connectOptions shape used by the test runner. When passed as an object,
     * exposeNetwork, headers, slowMo, and timeout are forwarded to the
     * underlying connect call.
     */
    remoteEndpoint?: string | playwright.ConnectOptions & { endpoint: string };
/**
     * Paths to TypeScript files to add as initialization scripts for Playwright page.
     */
    initPage?: string[];
/**
     * Paths to JavaScript files to add as initialization scripts.
     * The scripts will be evaluated in every page before any of the page's scripts.
     */
    initScript?: string[];
  },
/**
   * Connect to a running browser instance (Edge/Chrome only). If specified, browser
   * config is ignored.
   * Requires the "Playwright Extension" to be installed.
   */
  extension?: boolean;
server?: {
    /**
     * The port to listen on for SSE or MCP transport.
     */
    port?: number;
/**
     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
     */
    host?: string;
/**
     * The hosts this server is allowed to serve from. Defaults to the host server is bound to.
     * This is not for CORS, but rather for the DNS rebinding protection.
     */
    allowedHosts?: string[];
  },
/**
   * List of enabled tool capabilities. Possible values:
   *   - 'core': Core browser automation features.
   *   - 'pdf': PDF generation and manipulation.
   *   - 'vision': Coordinate-based interactions.
   *   - 'devtools': Developer tools features.
   */
  capabilities?: ToolCapability[];
/**
   * Whether to save the Playwright session into the output directory.
   */
  saveSession?: boolean;
/**
   * Reuse the same browser context between all connected HTTP clients.
   */
  sharedBrowserContext?: boolean;
/**
   * Secrets are used to replace matching plain text in the tool responses to prevent the LLM
   * from accidentally getting sensitive data. It is a convenience and not a security feature,
   * make sure to always examine information coming in and from the tool on the client.
   */
  secrets?: Record<string, string>;
/**
   * The directory to save output files.
   */
  outputDir?: string;
/**
   * Threshold for evicting old output files, in bytes.
   */
  outputMaxSize?: number;
console?: {
    /**
     * The level of console messages to return. Each level includes the messages of more severe levels. Defaults to "info".
     */
    level?: 'error' | 'warning' | 'info' | 'debug';
  },
network?: {
    /**
     * List of origins to allow the browser to request. Default is to allow all. Origins matching both allowedOrigins and blockedOrigins will be blocked.
     *
     * Supported formats:
     * - Full origin: https://example.com:8080 - matches only that origin
     * - Wildcard port: http://localhost:* - matches any port on localhost with http protocol
     */
    allowedOrigins?: string[];
/**
     * List of origins to block the browser to request. Origins matching both allowedOrigins and blockedOrigins will be blocked.
     *
     * Supported formats:
     * - Full origin: https://example.com:8080 - matches only that origin
     * - Wildcard port: http://localhost:* - matches any port on localhost with http protocol
     */
    blockedOrigins?: string[];
  };
/**
   * Specify the attribute to use for test ids, defaults to "data-testid".
   */
  testIdAttribute?: string;
timeouts?: {
    /*
     * Configures default action timeout: https://playwright.dev/docs/api/class-page#page-set-default-timeout. Defaults to 5000ms.
     */
    action?: number;
/*
     * Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.
     */
    navigation?: number;
/**
     * Configures default expect timeout: https://playwright.dev/docs/test-timeouts#expect-timeout. Defaults to 5000ms.
     */
    expect?: number;
/**
     * How long to wait after each action for triggered work (navigations, requests) to settle before responding. Defaults to 500ms.
     */
    settle?: number;
  };
/**
   * 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.
   */
  imageResponses?: 'allow' | 'omit';
snapshot?: {
    /**
     * When taking snapshots for responses, specifies the mode to use.
     */
    mode?: 'full' | 'none';
/**
     * Whether to include each element's bounding box as [box=x,y,width,height] in snapshots.
     * Coordinates are viewport-relative, in CSS pixels (Element.getBoundingClientRect).
     */
    boxes?: boolean;
  };
/**
   * allowUnrestrictedFileAccess acts as a guardrail to prevent the LLM from accidentally
   * wandering outside its intended workspace. It is a convenience defense to catch unintended
   * file access, not a secure boundary; a deliberate attempt to reach other directories can be
   * easily worked around, so always rely on client-level permissions for true security.
   */
  allowUnrestrictedFileAccess?: boolean;
/**
   * Specify the language to use for code generation.
   */
  codegen?: 'typescript' | 'python' | 'java' | 'csharp' | 'none';
}

</details>

独立 MCP server

当在没有显示器的系统上运行 headed browser，或从 IDE 的 worker 进程中运行时，请在具有 DISPLAY 的环境中运行 MCP server，并传递 --port 标志以启用 HTTP transport。

npx @playwright/mcp@latest --port 8931

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

Playwright MCP 不是一个安全边界。请参阅 MCP Security Best Practices 以获取关于保障部署安全的指南。

<details>
<summary><b>Docker</b></summary>

NOTE: 目前 Docker 实现仅支持 headless chromium。

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  --name playwright \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  /app/cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0

您可以自行构建 Docker 镜像。

docker build -t mcr.microsoft.com/playwright/mcp .

<details>
<summary><b>编程用法</b></summary>

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

Tools

<!--- Tools generated by update-readme.js -->

<details>
<summary><b>Core automation</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->

• browser_click

<!-- NOTE: This has been generated via update-readme.js -->

• browser_close

<!-- NOTE: This has been generated via update-readme.js -->- browser_console_messages
- Title: 获取控制台消息
- Description: 返回所有控制台消息
- Parameters:
- level (string): 要返回的控制台消息级别。每个级别包含更严重级别的消息。默认为 "info"。
- all (boolean, optional): 返回自会话开始以来所有控制台消息，而不仅仅是自上次导航以来的消息。默认为 false。
- filename (string, optional): 保存控制台消息的文件名。如果未提供，消息将以文本形式返回。
- Read-only: true

<!-- NOTE: This has been generated via update-readme.js -->

• browser_drag

<!-- NOTE: This has been generated via update-readme.js -->- browser_drop
- Title: 将文件或数据拖放到元素上
- Description: 将文件或 MIME 类型数据拖放到元素上，模拟从页面外部拖入。必须提供 paths 或 data 其中之一。
- Parameters:
- element (string, optional): 用于获取与该元素交互权限的可读元素描述
- target (string): 页面快照中的精确目标元素引用，或唯一的元素选择器
- paths (array, optional): 要拖放到元素上的文件的绝对路径。
- data (object, optional): 要拖放的数据，为 MIME 类型到字符串值的映射（例如 {"text/plain": "hello", "text/uri-list": "https://example.com"}）。
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_evaluate

<!-- NOTE: This has been generated via update-readme.js -->- browser_file_upload
- Title: 上传文件
- Description: 上传一个或多个文件
- Parameters:
- paths (array, optional): 要上传文件的绝对路径。可以是单个文件或多个文件。如果省略，则取消文件选择。
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_fill_form

<!-- NOTE: This has been generated via update-readme.js -->

• browser_find

<!-- NOTE: This has been generated via update-readme.js -->- browser_handle_dialog
- Title: 处理对话框
- Description: 处理对话框
- Parameters:
- accept (boolean): 是否接受对话框。
- promptText (string, optional): 如果是提示对话框，则为提示文本。
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_hover

<!-- NOTE: This has been generated via update-readme.js -->

• browser_navigate

<!-- NOTE: This has been generated via update-readme.js -->

• browser_navigate_back

<!-- NOTE: This has been generated via update-readme.js -->- browser_network_request
- Title: 显示网络请求详情
- Description: 返回单个网络请求的完整详情（headers 和 body），如果设置了 part 则返回单个部分。请使用 browser_network_requests 中提供的编号。
- Parameters:
- index (integer): 请求的索引（从 1 开始），由 browser_network_requests 打印。
- part (string, optional): 仅返回请求的此部分。省略则返回完整详情。
- filename (string, optional): 保存结果的文件名。如果未提供，则以文本形式返回输出。
- Read-only: true

<!-- NOTE: This has been generated via update-readme.js -->

• browser_network_requests

<!-- NOTE: This has been generated via update-readme.js -->- browser_press_key
- Title: 按下按键
- Description: 按下键盘上的某个按键
- Parameters:
- key (string): 要按下的按键名称或要生成的字符，例如 ArrowLeft 或 a
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_resize

<!-- NOTE: This has been generated via update-readme.js -->

• browser_run_code_unsafe

<!-- NOTE: This has been generated via update-readme.js -->- browser_select_option
- Title: 选择选项
- Description: 在下拉列表中选择一个选项
- Parameters:
- element (string, optional): 用于获取与该元素交互权限的可读元素描述
- target (string): 来自页面快照的精确目标元素引用，或唯一的元素选择器
- values (array): 在下拉列表中选择的值数组。可以是单个值或多个值。
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_snapshot

<!-- NOTE: This has been generated via update-readme.js -->- browser_take_screenshot
- Title: 截屏
- Description: 对当前页面进行截屏。你不能基于截屏执行操作，执行操作请使用 browser_snapshot。
- Parameters:
- element (string, optional): 用于获取与该元素交互权限的可读元素描述
- target (string, optional): 来自页面 snapshot 的精确目标元素引用，或唯一的元素选择器
- type (string, optional): 截屏的图像格式。如果未设置，则从文件名扩展名推断，否则默认为 png。
- filename (string, optional): 保存截屏的文件名。如果未指定，默认为 page-{timestamp}.{png|jpeg|webp}。建议使用相对文件名以保持在输出目录内。
- fullPage (boolean, optional): 为 true 时，截取整个可滚动页面的屏幕截图，而非当前可见的视口。不能与元素截屏同时使用。
- scale (string): 图像分辨率缩放。"css" 生成以 CSS 像素为单位的截屏（较小，跨设备一致）。"device" 生成使用设备像素的高分辨率截屏（较大，考虑设备像素比）。默认为 css。
- Read-only: true

<!-- NOTE: This has been generated via update-readme.js -->- browser_type
- Title: 输入文本
- Description: 在可编辑元素中输入文本
- Parameters:
- element (string, optional): 用于获取元素交互权限的可读元素描述
- target (string): 来自页面快照的精确目标元素引用，或唯一的元素选择器
- text (string): 要输入到元素中的文本
- submit (boolean, optional): 是否提交输入文本（之后按下 Enter）
- slowly (boolean, optional): 是否逐个字符输入。适用于触发页面的按键处理器。默认情况下，整个文本一次性填充。
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_wait_for

</details>

<details>
<summary><b>标签页管理</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->- browser_tabs
- Title: 管理标签页
- Description: 列出、创建、关闭或选择浏览器标签页。
- Parameters:
- action (string): 要执行的操作
- index (number, optional): 标签页索引，用于 close/select。如果 close 时省略，则关闭当前标签页。
- url (string, optional): 新标签页要跳转的 URL，用于 new。
- Read-only: false

</details>

<details>
<summary><b>浏览器安装</b></summary>

</details>

<details>
<summary><b>配置 (通过 --caps=config 启用)</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->

• browser_get_config

</details>

<details>
<summary><b>网络 (通过 --caps=network 启用)</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->

• browser_network_state_set

<!-- NOTE: This has been generated via update-readme.js -->- browser_route
- Title: Mock 网络请求
- Description: 设置一个路由以 Mock 匹配特定 URL 模式的网络请求
- Parameters:
- pattern (string): 要匹配的 URL 模式（例如 "/api/users", "/*.{png,jpg}"）
- status (number, optional): 要返回的 HTTP 状态码（默认值：200）
- body (string, optional): 响应体（文本或 JSON 字符串）
- contentType (string, optional): Content-Type 请求头（例如 "application/json", "text/html"）
- headers (array, optional): 要添加的请求头，格式为 "Name: Value"
- removeHeaders (string, optional): 要从请求中移除的请求头名称列表，以逗号分隔
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_route_list

<!-- NOTE: This has been generated via update-readme.js -->

• browser_unroute

</details>

<details>
<summary><b>Storage (通过 --caps=storage 启用)</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->- browser_cookie_clear
- Title: 清除 cookies
- Description: 清除所有 cookies
- Parameters: None
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_cookie_delete

<!-- NOTE: This has been generated via update-readme.js -->

• browser_cookie_get

<!-- NOTE: This has been generated via update-readme.js -->

• browser_cookie_list

<!-- NOTE: This has been generated via update-readme.js -->- browser_cookie_set
- Title: 设置 cookie
- Description: 设置一个 cookie，支持可选标志（domain, path, expires, httpOnly, secure, sameSite）
- Parameters:
- name (string): Cookie 名称
- value (string): Cookie 值
- domain (string, optional): Cookie 域名
- path (string, optional): Cookie 路径
- expires (number, optional): Cookie 过期时间（Unix 时间戳）
- httpOnly (boolean, optional): Cookie 是否仅限 HTTP
- secure (boolean, optional): Cookie 是否安全
- sameSite (string, optional): Cookie SameSite 属性
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_localstorage_clear

<!-- NOTE: This has been generated via update-readme.js -->

• browser_localstorage_delete

<!-- NOTE: This has been generated via update-readme.js -->

• browser_localstorage_get

<!-- NOTE: This has been generated via update-readme.js -->- browser_localstorage_list
- Title: 列出 localStorage
- Description: 列出所有 localStorage 键值对
- Parameters: None
- Read-only: true

<!-- NOTE: This has been generated via update-readme.js -->

• browser_localstorage_set

<!-- NOTE: This has been generated via update-readme.js -->

• browser_sessionstorage_clear

<!-- NOTE: This has been generated via update-readme.js -->

• browser_sessionstorage_delete

<!-- NOTE: This has been generated via update-readme.js -->

• browser_sessionstorage_get

<!-- NOTE: This has been generated via update-readme.js -->

• browser_sessionstorage_list

<!-- NOTE: This has been generated via update-readme.js -->- browser_sessionstorage_set
- Title: 设置 sessionStorage 项
- Description: 设置一个 sessionStorage 项
- Parameters:
- key (string): 要设置的键
- value (string): 要设置的值
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_set_storage_state

<!-- NOTE: This has been generated via update-readme.js -->

• browser_storage_state

</details>

<details>
<summary><b>DevTools (通过 --caps=devtools 启用)</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->

• browser_annotate

• browser_hide_highlight

<!-- NOTE: This has been generated via update-readme.js -->

• browser_highlight

<!-- NOTE: This has been generated via update-readme.js -->- browser_resume
- Title: 恢复暂停的脚本执行
- Description: 恢复之前暂停的脚本执行。当 step 设置为 true 时，执行将在下一个动作前再次暂停。
- Parameters:
- step (boolean, optional): 当为 true 时，执行将在下一个动作前再次暂停，以便进行单步调试。
- location (string, optional): 在特定的 <file>:<line> 处暂停执行，例如 "example.spec.ts:42"。
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_start_tracing

<!-- NOTE: This has been generated via update-readme.js -->

• browser_start_video

<!-- NOTE: This has been generated via update-readme.js -->

• browser_stop_tracing

<!-- NOTE: This has been generated via update-readme.js -->

• browser_stop_video

<!-- NOTE: This has been generated via update-readme.js -->- browser_video_chapter
- Title: 视频章节
- Description: 在视频录制中添加章节标记。显示带有模糊背景的全屏章节卡片。
- Parameters:
- title (string): 章节标题
- description (string, optional): 章节描述
- duration (number, optional): 显示章节卡片的时长（毫秒）
- Read-only: true

<!-- NOTE: This has been generated via update-readme.js -->

• browser_video_hide_actions

<!-- NOTE: This has been generated via update-readme.js -->

• browser_video_show_actions

</details><details>
<summary><b>基于坐标的（通过 --caps=vision 启用）</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->

• browser_mouse_click_xy

<!-- NOTE: This has been generated via update-readme.js -->

• browser_mouse_down

<!-- NOTE: This has been generated via update-readme.js -->

• browser_mouse_drag_xy

<!-- NOTE: This has been generated via update-readme.js -->- browser_mouse_move_xy
- Title: 移动鼠标
- Description: 将鼠标移动到指定位置
- Parameters:
- x (number): X 坐标
- y (number): Y 坐标
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_mouse_up

<!-- NOTE: This has been generated via update-readme.js -->

• browser_mouse_wheel

</details>

<details>
<summary><b>PDF 生成 (通过 --caps=pdf 启用)</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->

• browser_pdf_save

</details>

<details>
<summary><b>测试断言 (通过 --caps=testing 启用)</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->- browser_generate_locator
- Title: 为元素创建定位器
- Description: 为给定元素生成用于测试的定位器
- Parameters:
- element (string, optional): 用于获取元素交互权限的可读元素描述
- target (string): 来自页面快照的精确目标元素引用，或唯一的元素选择器
- Read-only: true

<!-- NOTE: This has been generated via update-readme.js -->

• browser_verify_element_visible

<!-- NOTE: This has been generated via update-readme.js -->

• browser_verify_list_visible

<!-- NOTE: This has been generated via update-readme.js -->- browser_verify_text_visible
- Title: 验证文本可见
- Description: 验证页面上是否存在可见文本。如果可能，优先使用 browser_verify_element_visible。
- Parameters:
- text (string): 要验证的 TEXT。可以在快照中通过 - role "Accessible Name": {TEXT} 或 - text: {TEXT} 找到。
- Read-only: false

<!-- NOTE: This has been generated via update-readme.js -->

• browser_verify_value

</details>

<!--- End of tools generated section -->