### Setup commands Source: https://swimmwatch.github.io/cloakbrowser-mcp/development Install dependencies, build the project, and run the CLI with --help. ```bash npm install npm run build node dist/cli.js --help ``` -------------------------------- ### Docs commands Source: https://swimmwatch.github.io/cloakbrowser-mcp/development Install documentation dependencies, build assets, serve docs, and build the docs site. ```bash npm run docs:install npm run docs:assets npm run docs:serve npm run docs:build ``` -------------------------------- ### Start the Docker container Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/docker-streamable-http-reverse-proxy Starts the container with the specified authentication token, volume mapping, and network configuration to listen on the host loopback. ```bash export MCP_AUTH_TOKEN="replace-with-a-secret-token" docker run --rm --init -p 127.0.0.1:3000:3000 \ -e CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN="$MCP_AUTH_TOKEN" \ -v "$PWD/artifacts:/data" \ swimmwatch/cloakbrowser-mcp:latest \ --transport streamable-http --http-host 0.0.0.0 --http-port 3000 ``` -------------------------------- ### Install dependencies and run checks Source: https://swimmwatch.github.io/cloakbrowser-mcp/contributing?q= Run these commands to install dependencies and execute the project's checks before opening a pull request. ```bash npm install npm run check ``` -------------------------------- ### Global Setup with Proxy Bypass List Source: https://swimmwatch.github.io/cloakbrowser-mcp/geoip-proxy-matching Adds a bypass list for hosts that should avoid the proxy. Uses PLAYWRIGHT_MCP_PROXY_BYPASS with comma-separated hosts. ```bash PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \ PLAYWRIGHT_MCP_PROXY_BYPASS=".internal,localhost" \ CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \ npx -y cloakbrowser-mcp@latest ``` -------------------------------- ### Global Setup with Proxy Server and GeoIP Matching Source: https://swimmwatch.github.io/cloakbrowser-mcp/geoip-proxy-matching Sets process-level environment variables for stdio clients and as default for Streamable HTTP sessions. Enables GeoIP proxy matching and passes the proxy server to CloakBrowser's launch preparation. ```bash PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \ CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \ npx -y cloakbrowser-mcp@latest ``` -------------------------------- ### Start CloakBrowser MCP server with streamable HTTP Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/connect-codex-cli Starts the CloakBrowser MCP server using streamable HTTP transport on port 3000. ```bash npx -y cloakbrowser-mcp@latest --transport streamable-http --http-port 3000 ``` -------------------------------- ### MCP client public URL example Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/docker-streamable-http-reverse-proxy Example of the public HTTPS URL to be used when configuring the MCP client. ```text https://mcp.example.com/mcp ``` -------------------------------- ### Probe streamable-http transport in CI Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/ci-smoke-test Starts the server in the background, probes the /readyz endpoint for connectivity, and cleans up the process. Use this only in short-lived CI jobs. ```bash npx -y cloakbrowser-mcp@latest --transport streamable-http --http-port 3000 & server_pid=$! for attempt in 1 2 3 4 5; do curl -fsS http://127.0.0.1:3000/readyz && break sleep 1 done kill "$server_pid" wait "$server_pid" || true ``` -------------------------------- ### Verify package Source: https://swimmwatch.github.io/cloakbrowser-mcp/testing?q= Builds the package, runs npm pack, checks the tarball file list, installs into a temporary project, and verifies CLI --version and --help. Also validates server.json against the published MCP server schema. ```bash npm run package:verify ``` -------------------------------- ### npm: Set persistent profile directory and start CloakBrowser MCP Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/persistent-login-profile Creates a profile directory and starts CloakBrowser MCP with the PLAYWRIGHT_MCP_USER_DATA_DIR environment variable pointing to it. Keep one active server per profile directory; the bridge rejects duplicate active use to reduce Chromium profile corruption risk. ```bash mkdir -p .profiles/default PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/default" \ npx -y cloakbrowser-mcp@latest ``` -------------------------------- ### Start cloakbrowser-mcp with HTTPS and certificate/key pair Source: https://swimmwatch.github.io/cloakbrowser-mcp/configuration?q= Use this command to run the bridge in Streamable HTTP mode with direct TLS. Requires --http-protocol https and either a certificate/key pair or a PFX file. For external exposure, also use --http-auth-token or terminate TLS at a trusted reverse proxy. ```bash cloakbrowser-mcp --transport streamable-http \ --http-protocol https \ --https-cert ./cert.pem \ --https-key ./key.pem ``` -------------------------------- ### Run CloakBrowser MCP with Streamable HTTP over HTTPS Source: https://swimmwatch.github.io/cloakbrowser-mcp/docker?q= Starts the container with Streamable HTTP using HTTPS. Mounts certificate files from ./certs and specifies the cert and key paths. The host-side bind remains on loopback. ```bash docker run --rm --init -p 127.0.0.1:3000:3000 \ -v "$PWD/artifacts:/data" \ -v "$PWD/certs:/certs:ro" \ swimmwatch/cloakbrowser-mcp:latest \ --transport streamable-http --http-host 0.0.0.0 --http-port 3000 \ --http-protocol https --https-cert /certs/cert.pem --https-key /certs/key.pem ``` -------------------------------- ### Start the Docker container with Streamable HTTP Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/docker-streamable-http-reverse-proxy?q= Runs the CloakBrowser MCP server in Docker, publishing port 3000 only on host loopback. Requires setting MCP_AUTH_TOKEN to a secret value. The container binds to 0.0.0.0 internally but is only accessible on 127.0.0.1. ```bash export MCP_AUTH_TOKEN="replace-with-a-secret-token" docker run --rm --init -p 127.0.0.1:3000:3000 \ -e CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN="$MCP_AUTH_TOKEN" \ -v "$PWD/artifacts:/data" \ swimmwatch/cloakbrowser-mcp:latest \ --transport streamable-http --http-host 0.0.0.0 --http-port 3000 ``` -------------------------------- ### Run CloakBrowser MCP with Streamable HTTP on loopback Source: https://swimmwatch.github.io/cloakbrowser-mcp/docker?q= Starts the container with Streamable HTTP transport bound to loopback. Publishes port 3000 on 127.0.0.1 and mounts the artifacts directory. Includes curl commands to check /healthz and /readyz endpoints. ```bash docker run --rm --init -p 127.0.0.1:3000:3000 \ -v "$PWD/artifacts:/data" \ swimmwatch/cloakbrowser-mcp:latest \ --transport streamable-http --http-host 0.0.0.0 --http-port 3000 curl http://127.0.0.1:3000/healthz curl http://127.0.0.1:3000/readyz ``` -------------------------------- ### Create volume and run CloakBrowser login and MCP container Source: https://swimmwatch.github.io/cloakbrowser-mcp/docker?q= Creates a named volume 'cloakbrowser-cache' and runs the CloakBrowser login command, then runs the MCP container with the same volume to persist license state. The login command uses --entrypoint node and the CLI path /opt/cloakbrowser-mcp/node_modules/cloakbrowser/dist/cli.js login. The MCP container mounts the volume and the current directory's artifacts folder to /data. ```bash docker volume create cloakbrowser-cache docker run --rm -it \ --entrypoint node \ -v cloakbrowser-cache:/home/node/.cloakbrowser \ swimmwatch/cloakbrowser-mcp:latest \ /opt/cloakbrowser-mcp/node_modules/cloakbrowser/dist/cli.js login docker run --rm --init -i \ -v cloakbrowser-cache:/home/node/.cloakbrowser \ -v "$PWD/artifacts:/data" \ swimmwatch/cloakbrowser-mcp:latest ``` -------------------------------- ### Configure Continue Source: https://swimmwatch.github.io/cloakbrowser-mcp/getting-started?q= Create the YAML configuration file for Continue. ```yaml name: CloakBrowser MCP version: 0.0.1 schema: v1 mcpServers: - name: CloakBrowser type: stdio command: npx args: - -y - cloakbrowser-mcp@latest ``` -------------------------------- ### Initialize Persistent Profile with npm Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/persistent-login-profile?q= Create a directory for the profile and launch the server with the PLAYWRIGHT_MCP_USER_DATA_DIR environment variable set to that path. ```bash mkdir -p .profiles/default PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/default" \ npx -y cloakbrowser-mcp@latest ``` -------------------------------- ### Run doctor command Source: https://swimmwatch.github.io/cloakbrowser-mcp/generated/cli?q= Run local diagnostics without starting the MCP bridge. Use --json to output diagnostics as JSON. ```text Usage: doctor [options] Run local diagnostics without starting the MCP bridge. Options: --json Output diagnostics as JSON. -h, --help display help for command ``` -------------------------------- ### Configure claude_desktop_config.json for Cloakbrowser Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/connect-claude-desktop Add this entry to your claude_desktop_config.json file to enable the server via stdio, then restart Claude Desktop. ```json { "mcpServers": { "cloakbrowser": { "command": "npx", "args": ["-y", "cloakbrowser-mcp@latest"] } } } ``` -------------------------------- ### Run npm package doctor check Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/ci-smoke-test Verifies Node.js, package metadata, Playwright MCP CLI resolution, and binary metadata without starting the bridge. ```bash npx -y cloakbrowser-mcp@latest doctor --json ``` -------------------------------- ### Add CloakBrowser MCP via stdio Source: https://swimmwatch.github.io/cloakbrowser-mcp/recipes/connect-codex-cli Registers CloakBrowser MCP with Codex CLI using stdio transport. Codex will start CloakBrowser MCP for the current machine. ```bash codex mcp add cloakbrowser -- npx -y cloakbrowser-mcp@latest ``` -------------------------------- ### Enable humanized input via CLI flags Source: https://swimmwatch.github.io/cloakbrowser-mcp/humanized-input-behavior Uses the explicit CLI flags --humanize and --human-preset careful to enable humanized behavior, equivalent to the environment variable setup. ```bash npx -y cloakbrowser-mcp@latest --humanize --human-preset careful ``` -------------------------------- ### Local Docker commands Source: https://swimmwatch.github.io/cloakbrowser-mcp/development Build the Docker image, run smoke tests, and run the container with a mounted artifacts volume. ```bash npm run docker:build npm run docker:smoke docker run --rm --init -i -v "$PWD/artifacts:/data" cloakbrowser-mcp:dev ``` -------------------------------- ### Run CloakBrowser MCP with npx Source: https://swimmwatch.github.io/cloakbrowser-mcp/getting-started?q= Execute the latest version of the CloakBrowser MCP server using npx. ```bash npx -y cloakbrowser-mcp@latest ``` -------------------------------- ### Configure VS Code Source: https://swimmwatch.github.io/cloakbrowser-mcp/getting-started?q= Add the server configuration to the workspace or user-level mcp.json file. ```json { "servers": { "cloakbrowser": { "type": "stdio", "command": "npx", "args": ["-y", "cloakbrowser-mcp@latest"] } } } ``` -------------------------------- ### cloakbrowser-mcp CLI Usage Source: https://swimmwatch.github.io/cloakbrowser-mcp/generated/cli Displays the full list of available options and commands for the cloakbrowser-mcp tool. ```text Usage: cloakbrowser-mcp [options] [command] Playwright MCP bridge backed by CloakBrowser. Options: -V, --version output the version number -h, --help display help for command Transport --transport MCP transport exposed by the bridge. (choices: "stdio", "streamable-http", default: stdio, env: CLOAK_PLAYWRIGHT_MCP_TRANSPORT) Bridge --geoip-proxy-match Match CloakBrowser timezone and locale to the configured proxy GeoIP. (default: false, env: CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH) --humanize Enable CloakBrowser human-like mouse, keyboard, and scroll behavior. (default: false, env: CLOAK_PLAYWRIGHT_MCP_HUMANIZE) --human-preset CloakBrowser human behavior preset. Used only when humanize is enabled. (choices: "default", "careful", default: default, env: CLOAK_PLAYWRIGHT_MCP_HUMAN_PRESET) --release-channel CloakBrowser binary release channel. (choices: "stable", "preview", default: stable, env: CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL) Streamable HTTP --http-protocol Streamable HTTP listener protocol. (choices: "http", "https", default: http, env: CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL) --http-host Streamable HTTP bind host. (default: 127.0.0.1, env: CLOAK_PLAYWRIGHT_MCP_HTTP_HOST) --http-port Streamable HTTP bind port. Use 0 for an ephemeral port in tests. (default: 3000, env: CLOAK_PLAYWRIGHT_MCP_HTTP_PORT) --http-endpoint Streamable HTTP endpoint path. Reserved probe paths: /healthz, /readyz. (default: /mcp, env: CLOAK_PLAYWRIGHT_MCP_HTTP_ENDPOINT) --http-auth-token Optional Bearer token required on Streamable HTTP requests. (env: CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN) --https-cert TLS certificate PEM file for HTTPS Streamable HTTP. (env: CLOAK_PLAYWRIGHT_MCP_HTTPS_CERT) --https-key TLS private key PEM file for HTTPS Streamable HTTP. (env: CLOAK_PLAYWRIGHT_MCP_HTTPS_KEY) --https-pfx TLS PFX/PKCS12 file for HTTPS Streamable HTTP. (env: CLOAK_PLAYWRIGHT_MCP_HTTPS_PFX) --https-passphrase Passphrase for an encrypted HTTPS key or PFX. (env: CLOAK_PLAYWRIGHT_MCP_HTTPS_PASSPHRASE) --http-session-backend Session metadata backend. Only memory is implemented in this release. (choices: "memory", default: memory, env: CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_BACKEND) --http-session-idle-ttl-ms Idle TTL for Streamable HTTP sessions. (default: 3600000, env: CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_IDLE_TTL_MS) --http-session-max Maximum active Streamable HTTP sessions in one process. (default: 32, env: CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_MAX) Commands: doctor [options] Run local diagnostics without starting the MCP bridge. ``` -------------------------------- ### Run Streamable HTTP with Docker Source: https://swimmwatch.github.io/cloakbrowser-mcp/docker Publishes the container port on loopback for local Streamable HTTP usage and verifies with health and readiness probes. ```bash docker run --rm --init -p 127.0.0.1:3000:3000 \ -v "$PWD/artifacts:/data" \ swimmwatch/cloakbrowser-mcp:latest \ --transport streamable-http --http-host 0.0.0.0 --http-port 3000 curl http://127.0.0.1:3000/healthz curl http://127.0.0.1:3000/readyz ``` -------------------------------- ### Build and smoke test Docker image Source: https://swimmwatch.github.io/cloakbrowser-mcp/docker?q= Commands to build the Docker image and run smoke tests locally. Requires npm and Docker. The build uses the pinned official Playwright MCP image as the runtime base, applies Debian security updates, removes the unused global npm payload, and installs the bridge under /opt/cloakbrowser-mcp. ```bash npm run docker:build npm run docker:smoke ``` -------------------------------- ### Run CloakBrowser MCP Container Source: https://swimmwatch.github.io/cloakbrowser-mcp/docker?q= Executes the CloakBrowser MCP container with a volume mount for artifacts. The --init flag is recommended to properly reap child processes created by browser automation. ```bash docker run --rm --init -i \ -v "$PWD/artifacts:/data" \ swimmwatch/cloakbrowser-mcp:latest ``` -------------------------------- ### Run local check Source: https://swimmwatch.github.io/cloakbrowser-mcp/contributor-guide?q= Execute the full check suite before committing changes. ```bash npm run check ``` -------------------------------- ### Compare upstream parity Source: https://swimmwatch.github.io/cloakbrowser-mcp/testing?q= Starts the official Playwright MCP Docker image and the CloakBrowser bridge image, compares upstream tool names, exercises the default browser tool surface on one fixture page, and verifies local Cloak introspection tools. The optional --report flag writes a JSON parity report. ```bash npm run bridge:compare npm run bridge:compare -- cloakbrowser-mcp:dev --report bridge-parity-report.json ```