CloakBrowser MCP

Run from Docker

docker pull swimmwatch/cloakbrowser-mcp:latest
docker run --rm --init -i \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

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

For direct HTTPS from the container, mount your TLS files and select HTTPS:

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

The Docker image is based on the pinned official Playwright MCP image, installs the bridge under /opt/cloakbrowser-mcp, writes artifacts to /data by default, and is published for linux/amd64 and linux/arm64. The same tags are also published to ghcr.io/swimmwatch/cloakbrowser-mcp.

Docker

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--init",
        "-i",
        "-v",
        "/tmp/cloakbrowser-artifacts:/data",
        "swimmwatch/cloakbrowser-mcp:latest"
      ]
    }
  }
}

MCP client configuration

Configuration

Use upstream PLAYWRIGHT_MCP_* variables for browser, artifact, timeout, network, and tool capability settings. Cloak-specific bridge toggles use CLOAK_PLAYWRIGHT_MCP_*. CLI flags are documented in the generated CLI Reference. GeoIP proxy matching and Streamable HTTP runtime proxy metadata are documented in GeoIP Proxy Matching.

Common variables:

Streamable HTTP clients can override the proxy per MCP session by passing bridge metadata in the initialize request:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "proxyServer": "http://user:pass@proxy.example:8080",
        "proxyBypass": ".internal,localhost",
        "geoipProxyMatch": true
      }
    }
  }
}

Runtime proxy metadata overrides PLAYWRIGHT_MCP_PROXY_SERVER and PLAYWRIGHT_MCP_PROXY_BYPASS for that HTTP session only. Stdio keeps using process-level environment and CLI configuration.

Authenticated HTTP proxies are supported with credentials embedded in proxyServer, for example http://user:pass@proxy.example:8080. Percent-encode credential characters that have URL meaning, such as @, :, /, ?, #, and %.

Enable CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true to align CloakBrowser timezone, language, and locale fingerprint flags with the selected proxy location. Streamable HTTP clients can set geoipProxyMatch per session to run different regional QA scenarios from one server process.

The old CLOAKBROWSER_MCP_* variables are not supported.