配置¶

使用上游 PLAYWRIGHT_MCP_* 变量来实现 Playwright MCP 行为。 仅将 CLOAK_PLAYWRIGHT_MCP_* 用于 Cloak 特有的桥接行为。

旧版 CLOAKBROWSER_MCP_* 变量已不被支持。 生成的 CLI 参考 是桥接 CLI 标志及其对应环境变量的权威列表。

桥接选项¶

CloakBrowser 许可证与 GitHub 登录¶

许可证设置使用上游 CloakBrowser CLI；cloakbrowser-mcp 不会添加登录或退出命令：

npx -y cloakbrowser@latest login
npx -y cloakbrowser@latest info
npx -y cloakbrowser@latest logout

login 可接受付费密钥，也可启动 GitHub 登录以获取免费层密钥。验证后的密钥存储在 ~/.cloakbrowser/license.key 中；logout 会删除该文件。info 会报告当前许可证 层级；对于 Pro 许可证，还会报告活动会话数。

也可以在 MCP 服务器环境中设置 CLOAKBROWSER_LICENSE_KEY。桥接器会将该变量转发给 上游/浏览器子进程，但不会记录它。当 CLOAKBROWSER_CACHE_DIR 指向包含 license.key 的自定义缓存时，CloakBrowser 会解析密钥，而桥接器只会从生成的浏览器 环境中转发该解析后的密钥。其他生成的环境条目不会被复制。

如果 CloakBrowser 拒绝提供的许可证密钥、无法验证该密钥或无法连接许可证 服务器，启动会因明确的 CloakBrowser 错误而失败。桥接会保留该错误；它不会 掩盖错误，也不会静默切换到其他浏览器或许可证级别。

已管理 CDP¶

托管的 Chrome 开发者工具协议 (CDP) 访问是需要明确选择加入的。它公开了 由 MCP 通过具备能力的方式控制的相同 Chromium 浏览器版本 发现 URL。仅配置端口池并不会启用 CDP。

每个 CLI 值仅覆盖其对应的环境变量。特别是， --no-cdp-enabled 覆盖 CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED=true，并且 --no-cdp-allow-remote 覆盖 CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE=true。 启用的会话在其上游子开始之前，如果没有端口池，将被拒绝。 一个有效的假值不会创建监听器、端口租赁或能力。

对于 stdio，该进程值直接适用：

cloakbrowser-mcp \
  --cdp-enabled \
  --cdp-port-range 9222

对于 Streamable HTTP，经过身份验证的平坦 cdpEnabled 布尔值 initialize 元数据覆盖该会话的进程默认设置。省略 字段继承流程值。这些示例明确选择了一个会话并 另一个出:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": true
      }
    }
  }
}

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": false
      }
    }
  }
}

一个启用 CDP 的 HTTP 会话拥有一个外部端口租用。已禁用的会话没有。 消耗池。分配是进程本地的，选择未租用的最低候选项， 如果所选的外部端口已被占用，则会立即使该会话失败。 关闭会话以释放端口，或在池耗尽时配置更大的范围。

从 cloakbrowser_bridge_info 检索当前的 URL，然后传递它的 structuredContent.cdp.discoveryUrl 到像 Playwright 的 CDP 客户 chromium.connectOverCDP()。将那个 URL 视为凭证：它包含一个随机值 每代能力，并且在浏览器更换后会变得过时。托管的 CDP 是 不是 Playwright 服务器端点。chromium.connect() 和当前的 Open WebUI 不支持 PLAYWRIGHT_WS_URL 流。

--cdp-advertised-scheme https 发布 https 发现和 wss WebSocket 链接 仅此而已。该桥不为受管 CDP 提供 TLS：它的外部监听器和 Chromium 保持明文 HTTP/WebSocket。必须有运营商拥有的 TLS 终端器 在相同的广告租用端口上监听，保留广告的 Host 和 Origin 授权，并将其一对一地转发给该会话的明文监听器。

CDP 启用从 MCP 初始化期间开始 Chromium，以便所有权和外部 可以验证就绪情况。将 MCP 客户端初始化超时配置为至少 60 秒。当启用管理的 CDP 时，由用户提供的 CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS 不得包含 --remote-debugging-port， --remote-debugging-address，或 --remote-debugging-pipe（包括 = 形式）。 Playwright 自身的内部 --remote-debugging-pipe 仍然保持启用状态，同时 由网桥管理的回环 TCP 端点。

请参阅 工具, Docker, 安全，以及 架构 用于发现状态、部署， 限制和重启行为。

CloakBrowser 发布通道¶

CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL 选择 CloakBrowser 二进制文件的发布通道。默认值为 stable。preview 请求 Pro 浏览器预览构建，且仅适用于 Pro 许可证。显式固定的 CLOAKBROWSER_VERSION 优先。如果平台没有可用的 Preview，CloakBrowser 会回退到 Stable。

发布通道在桥接进程启动时选定。它适用于所有 Streamable HTTP 会话，且不能在 initialize 元数据中设置或覆盖。请重启桥接进程以更改它。

自定义 CloakBrowser 二进制文件¶

--binary-path <path> 为当前桥接进程选择自定义的 CloakBrowser 可执行文件。 CLOAKBROWSER_BINARY_PATH 为基于环境的部署提供相同设置；CLI 选项优先。桥接会 解析该路径，要求它是可读的普通文件，并将解析后的路径写入生成的 Playwright MCP 配置的 browser.launchOptions.executablePath。

npx -y cloakbrowser-mcp@latest --binary-path /opt/cloakbrowser/chrome

桥接不会下载或更新自定义可执行文件。未选择自定义路径时，可使用 CLOAKBROWSER_VERSION 固定由 CloakBrowser 管理的二进制版本。

对于 Streamable HTTP，所选二进制文件属于桥接进程，并由其创建的每个 MCP 会话 使用。initialize 元数据不能选择或覆盖可执行文件路径；需要不同二进制文件的 会话应运行单独的桥接进程。

当所选二进制文件实现 document.modelContext 时，上游 Playwright MCP 可在页面快照后添加 webmcp_<page-tool> 形式的工具。它会发送 tools/list_changed；桥接会转发该通知和更新后的工具列表。每个动态工具的名称和模式由页面定义。

GeoIP 代理匹配¶

将 CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true 与 PLAYWRIGHT_MCP_PROXY_SERVER 一起设置，以根据代理出口位置推导 CloakBrowser 的 时区、语言和区域设置指纹标志。对于受支持的二进制文件，CloakBrowser 会选择原生 URL 内联身份验证；对于较旧的二进制文件，则保留 Playwright 代理对象作为回退。

有关配置示例、运行时 可流式传输的 HTTP 代理元数据、用例、优先级规则和限制，请参阅 GeoIP 代理匹配。

匹配采用 fail-closed 行为：如果 CloakBrowser 无法解析代理出口 IP、GeoIP 数据库、时区或区域设置，浏览器不会以部分匹配的指纹启动。GeoIP 解析最长为 20 秒；首次下载离线 GeoIP 数据库独立进行，可能需要更长时间。

拟人化的输入行为¶

将 CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true 设置为启用 CloakBrowser 的类人 鼠标、键盘和滚动层，用于页面交互。 该桥接器通过 Playwright MCP 的页面初始化钩子应用此设置，因此上游浏览器工具 的架构保持不变。

有关配置示例、 运行时可流式传输的 HTTP 元数据、用例及限制，请参阅 人性化输入行为。

Chrome 扩展¶

Chrome 扩展会在浏览器启动时加载，因此请在启动桥接器之前，或在创建 Streamable HTTP 会话之前完成配置。扩展必须是已解压的目录，并且需要 持久化配置文件：

PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/default" \
  CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS='["/absolute/path/to/my-extension"]' \
  npx -y cloakbrowser-mcp@latest

对于 Streamable HTTP，请在 initialize 元数据中传入配置文件目录和扩展 目录：

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "userDataDir": "/absolute/path/to/profile",
        "extensionPaths": ["/absolute/path/to/my-extension"]
      }
    }
  }
}

更改扩展文件或扩展路径后，请重启桥接器或创建新的 HTTP 会话。当路径包含 逗号、传入多个扩展，或使用带盘符的 Windows 路径时，请为 CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS 使用 JSON 数组。

Playwright Extension 连接模式¶

此模式通过已安装在 Chrome 或 Edge 配置文件中的官方 Playwright Extension 连接，与通过 CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS 加载解压扩展不同。对于 stdio，请设置 PLAYWRIGHT_MCP_EXTENSION=true、PLAYWRIGHT_MCP_EXTENSION_TOKEN、PLAYWRIGHT_MCP_USER_DATA_DIR，并可设置仅含一个相对路径段的 PLAYWRIGHT_MCP_PROFILE_DIR_NAME。在 Streamable HTTP 中，extensionMode、profileDirName 和 userDataDir 元数据覆盖进程值，但 token 只能来自进程环境。并行会话必须使用不同的 userDataDir；launch、CDP、proxy、GeoIP、humanization、context 和 extensionPaths 配置与此模式不兼容。

可流式传输的 HTTP 运行时元数据¶

支持流式传输的 HTTP 客户端可以通过在 initialize 请求中添加 特定于桥接器的元数据，为每个 MCP 会话选择相应的运行时选项：

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "proxyServer": "http://user:pass@proxy.example:8080",
        "proxyBypass": ".internal,localhost",
        "geoipProxyMatch": true,
        "headless": false,
        "humanize": true,
        "humanPreset": "careful",
        "userDataDir": "/absolute/path/to/profile",
        "contextOptions": {
          "viewport": { "width": 1280, "height": 720 },
          "locale": "en-US",
          "timezoneId": "America/New_York"
        },
        "extensionPaths": ["/absolute/path/to/extension"]
      }
    }
  }
}

proxyServer 在该 HTTP 会话中覆盖了 PLAYWRIGHT_MCP_PROXY_SERVER。 proxyBypass 仅在存在 proxyServer 时，才覆盖 PLAYWRIGHT_MCP_PROXY_BYPASS，但仅当 proxyServer 存在时 才生效。 geoipProxyMatch 可在无需重启 MCP 服务器的情况下， 启用或禁用该会话的 GeoIP 匹配功能。现有会话将保留其初始代理； 需创建新的 HTTP 会话才能切换位置。

humanize 可以为该会话启用或禁用人性化输入行为， 而不会影响其他会话。 humanPreset 可为该会话选择 default 或 careful ，但本身不会启用人性化行为。 现有 会话将保留在 initialize 期间捕获的行为。

在 Docker 中，headless: false 会按需启动私有虚拟显示器。在镜像外，有头会话仍需要可用的显示环境。

userDataDir 为该会话启用持久化 Chromium 配置文件，并覆盖 PLAYWRIGHT_MCP_USER_DATA_DIR。桥接器会将目录解析为平台原生绝对路径， 在缺失时创建它，验证其可写，并写入生成的 browser.userDataDir。 持久化配置文件会禁用该会话默认的 Streamable HTTP 隔离配置文件。桥接器会 拒绝同一进程内重复的活动配置文件目录；跨进程配置文件冲突仍由 Chromium/Playwright 报错。

contextOptions 会经过验证，并在 CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS 之上进行浅合并；嵌套对象会整体替换。支持的字段为 userAgent、 viewport、locale、timezoneId、colorScheme、permissions、 geolocation、extraHTTPHeaders、httpCredentials、ignoreHTTPSErrors、 offline、deviceScaleFactor、isMobile 和 hasTouch。本版本不支持任意 传递 BrowserContextOptions。

extensionPaths 必须指向现有目录，并且需要持久化的 userDataDir。 桥接器会将扩展路径解析为平台原生绝对路径，传给 CloakBrowser，并把生成的 Chromium 参数 --load-extension 和 --disable-extensions-except 写入生成的 Playwright MCP 配置。

经过身份验证的 HTTP 代理凭据可以嵌入到 proxyServer 中，例如 http://user:pass@proxy.example:8080。对具有 URL 含义的凭据 字符进行百分比编码，例如 @、 :、/、 ?、 #，以及 %。

对于受支持的 CloakBrowser 二进制文件，经过身份验证的 HTTP 代理会使用原生 URL 内联身份验证，桥接器则会移除重复的 Playwright 代理对象。较旧的二进制文件会保留 Playwright 代理对象作为兼容性回退。

有关多地点质量保证模式，请参阅 GeoIP 代理匹配。 有关交互真实性模式，请参阅 人性化输入行为。

上游选项¶

该桥接器将 PLAYWRIGHT_MCP_* 的设置转发给上游的 Playwright MCP。其中包括以下上游选项：

• PLAYWRIGHT_MCP_ALLOWED_ORIGINS
• PLAYWRIGHT_MCP_BLOCKED_ORIGINS
• PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS
• PLAYWRIGHT_MCP_CAPS
• PLAYWRIGHT_MCP_CONSOLE_LEVEL
• PLAYWRIGHT_MCP_IMAGE_RESPONSES
• PLAYWRIGHT_MCP_SNAPSHOT_MODE
• PLAYWRIGHT_MCP_STORAGE_STATE

有关完整的上游选项列表，请参阅上游 Playwright MCP 文档。

PLAYWRIGHT_MCP_CAPS=devtools 会由上游子进程继承，并启用该能力控制的 工具，无需桥接专用的 --caps 标志。

日志记录¶

可流式传输的 HTTP 模式会将易于人类阅读的启动和请求日志写入 stdout。Stdio 模式不会输出常规操作日志，因此 MCP JSON-RPC 的 stdout 保持协议纯净。命令行界面（CLI）启动时的致命错误仍会写入 stderr。

HTTPS¶

Streamable HTTP 默认使用本地 HTTP。若要选择直接 TLS，请使用 --http-protocol https 或 CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https 选择“直接 TLS”模式，然后提供证书/密钥对或 PFX 文件：

cloakbrowser-mcp --transport streamable-http \
  --http-protocol https \
  --https-cert ./cert.pem \
  --https-key ./key.pem

对于外部或非回环暴露，请使用 HTTPS 并配合 --http-auth-token，或者在可信的反向代理上终止 TLS，该代理还应强制执行身份验证和网络访问控制。

可流式传输的 HTTP 会话¶

每个 Streamable HTTP MCP 会话都拥有自己的桥接运行时和上游 Playwright MCP 子进程。HTTP 会话使用隔离的浏览器配置文件运行上游 Playwright MCP，因此并发用户不会争夺同一个持久性 Chromium 配置文件。 内置的 memory 会话后端仅存储会话 ID、时间戳、过期时间和状态等元数据。 浏览器状态仍保留在活跃的上游子进程中，而相关资源仍由 PLAYWRIGHT_MCP_OUTPUT_DIR 控制。

对于水平扩展，请在负载均衡器后运行多个服务器副本，并使用以 mcp-session-id 头为键的粘性会话。 未来的 Redis、Postgres 或 SQLite 后端可以协调元数据和锁，但当拥有该会话的进程退出后，它们无法恢复正在运行的浏览器会话。

可流式传输的 HTTP 探针¶

当桥接器运行时，若使用 --transport streamable-http，它会在与 MCP 端点相同的主机和端口上暴露固定的探针端点：

• GET /healthz 返回进程健康状况元数据： status、version、 transport，以及 uptimeMs。
• GET /readyz 返回就绪状态元数据和会话容量： sessions.active、sessions.pending、 sessions.max 以及 sessions.available。

当会话容量可用时，就绪状态返回 HTTP 200，而当 503，而当 active + pending >= max 时则返回 active + pending >= max。 如果配置了 --http-auth-token 或 CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN 已配置，则这两个探针都需要与 MCP 请求相同的 Authorization: Bearer ... 标头。 如果没有身份验证令牌，探针将在配置的 HTTP 绑定地址上保持开放状态。

更多实用路径¶

要在 upstream Playwright MCP 和本包之间选择，请查看对比。快速任务请使用操作示例：持久配置文件、扩展、reverse proxy、区域 QA、Claude Desktop、Codex CLI 和 CI 冒烟测试。