CloakBrowser MCP

https://swimmwatch.github.io/cloakbrowser-mcp/
Admin
CloakBrowser MCP is a Playwright MCP-compatible browser automation server that runs upstream...
Tokens:41,581
Snippets:385
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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 <mode>                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 <preset>           CloakBrowser human behavior preset. Used
                                    only when humanize is enabled. (choices:
                                    "default", "careful", default: default, env:
                                    CLOAK_PLAYWRIGHT_MCP_HUMAN_PRESET)
  --release-channel <channel>       CloakBrowser binary release channel.
                                    (choices: "stable", "preview", default:
                                    stable, env:
                                    CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL)

Streamable HTTP
  --http-protocol <protocol>        Streamable HTTP listener protocol. (choices:
                                    "http", "https", default: http, env:
                                    CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL)
  --http-host <host>                Streamable HTTP bind host. (default:
                                    127.0.0.1, env:
                                    CLOAK_PLAYWRIGHT_MCP_HTTP_HOST)
  --http-port <port>                Streamable HTTP bind port. Use 0 for an
                                    ephemeral port in tests. (default: 3000,
                                    env: CLOAK_PLAYWRIGHT_MCP_HTTP_PORT)
  --http-endpoint <path>            Streamable HTTP endpoint path. Reserved
                                    probe paths: /healthz, /readyz. (default:
                                    /mcp, env:
                                    CLOAK_PLAYWRIGHT_MCP_HTTP_ENDPOINT)
  --http-auth-token <token>         Optional Bearer token required on Streamable
                                    HTTP requests. (env:
                                    CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN)
  --https-cert <path>               TLS certificate PEM file for HTTPS
                                    Streamable HTTP. (env:
                                    CLOAK_PLAYWRIGHT_MCP_HTTPS_CERT)
  --https-key <path>                TLS private key PEM file for HTTPS
                                    Streamable HTTP. (env:
                                    CLOAK_PLAYWRIGHT_MCP_HTTPS_KEY)
  --https-pfx <path>                TLS PFX/PKCS12 file for HTTPS Streamable
                                    HTTP. (env: CLOAK_PLAYWRIGHT_MCP_HTTPS_PFX)
  --https-passphrase <value>        Passphrase for an encrypted HTTPS key or
                                    PFX. (env:
                                    CLOAK_PLAYWRIGHT_MCP_HTTPS_PASSPHRASE)
  --http-session-backend <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 <ms>   Idle TTL for Streamable HTTP sessions.
                                    (default: 3600000, env:
                                    CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_IDLE_TTL_MS)
  --http-session-max <count>        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

```
Tokens:
Raw